gallery-dl 图片批量下载教程：安装、常用命令与登录配置

gallery-dl 是什么，适合谁用

gallery-dl 是 GitHub 上的开源命令行下载器（仓库 mikf/gallery-dl），内置数百个网站的专用提取器，覆盖 Pixiv、Twitter/X、Danbooru、Tumblr、微博等图文站点。输入一个网址，它会解析出页面内全部图片并按规则自动保存，适合整包相册、漫画章节、账号历史图这类场景，比浏览器扩展更稳定，也方便写脚本定时运行。

三种安装方式

• Windows 独立版：在 GitHub Releases 页下载 gallery-dl.exe，放到任意目录即用，无需安装 Python；
• pip 安装：需 Python 3.8 及以上，执行 pip install -U gallery-dl；
• 包管理器：Windows 用 scoop install gallery-dl，macOS/Linux 用 brew install gallery-dl。

一条命令开始批量下载

终端中输入 gallery-dl 加网址即可，例如 gallery-dl "https://www.pixiv.net/users/12345"，文件默认存到当前目录下的 gallery-dl 分类文件夹。常用参数：

• -d D:/pics：指定保存目录；
• --range 1-50：只下载前 50 张；
• --filter "width >= 1920 and extension in ('jpg','png')"：按分辨率、格式筛选；
• -i list.txt：从文本文件批量读取网址，一行一个；
• --download-archive done.db：记录已下载内容，重复运行自动跳过，适合定期追更。

需要登录的站点怎么配置

Pixiv 全站需要登录，Twitter/X、Instagram 的媒体也只对登录用户可见。最省事的做法是复用浏览器登录状态：

gallery-dl --cookies-from-browser chrome "https://x.com/用户名"

也可以用导出的 cookies.txt：加参数 --cookies cookies.txt。-u/-p 账号密码方式对部分站点仍有效，但遇到两步验证会失败，优先用 cookies。下载视频时确认 ffmpeg 已加入系统 PATH，否则音视频合成会失败。

把偏好写进 config.json

配置文件路径：Windows 为 %APPDATA%/gallery-dl/config.json，macOS/Linux 为 ~/.config/gallery-dl/config.json。示例：

{"base-directory": "D:/gallery/", "filename": "{category}_{id}_{num}.{extension}", "extractor": {"pixiv": {"cookies": "pixiv_cookies.txt", "sleep": 2}}}

base-directory 设全局保存位置，filename 自定义命名规则，sleep 控制请求间隔秒数，可降低限流与封号风险。

常见报错与注意事项

• 突然抓不到内容：多半是目标站点改版，先升级到最新版（pip install -U gallery-dl），再用 --verbose 查看日志定位问题；
• 终端里的网址务必加英文引号，URL 中的 & 和 ? 会被截断；
• 独立 exe 双击闪退是正常现象，它是命令行程序，请在 cmd 中运行；
• 保持合理请求频率，仅用于个人备份，遵守目标站点条款。