gallery-dl
gallery-dl is a command-line program to download image galleries and
collections from several image hosting sites (see Supported
Sites). It is a cross-platform tool with many
configuration options and powerful filenaming
capabilities.
::: contents
:::
Dependencies
Optional
- FFmpeg: Pixiv Ugoira conversion
- yt-dlp or
youtube-dl: Video
downloads - PySocks: SOCKS proxy support
- brotli or
brotlicffi: Brotli
compression support
Installation
Pip
The stable releases of gallery-dl are distributed on
PyPI and can be easily installed or upgraded using
pip:
python3 -m pip install -U gallery-dl
Installing the latest dev version directly from GitHub can be done with
pip as well:
python3 -m pip install -U -I --no-deps --no-cache-dir https://github.com/mikf/gallery-dl/archive/master.tar.gz
Note: Windows users should use py -3
instead of python3
.
It is advised to use the latest version of
pip, including the essential packages
setuptools
and wheel
. To ensure these packages are up-to-date, run
python3 -m pip install --upgrade pip setuptools wheel
Standalone Executable
Prebuilt executable files with a Python interpreter and required Python
packages included are available for
Nightly Builds
| Executables build from the latest commit can be found at
| https://github.com/mikf/gallery-dl/actions/workflows/executables.yml
Snap
Linux users that are using a distro that is supported by
Snapd can install
gallery-dl from the Snap Store:
snap install gallery-dl
Chocolatey
Windows users that have Chocolatey
installed can install gallery-dl from the Chocolatey Community
Packages repository:
choco install gallery-dl
Scoop
gallery-dl is also available in the Scoop "main"
bucket for Windows users:
scoop install gallery-dl
Homebrew
For macOS or Linux users using Homebrew:
brew install gallery-dl
Usage
To use gallery-dl simply call it with the URLs you wish to download
images from:
gallery-dl [OPTIONS]... URLS...
Use gallery-dl --help
or see docs/options.md for a
full list of all command-line options.
Examples
Download images; in this case from danbooru via tag search for
'bonocho':
gallery-dl "https://danbooru.donmai.us/posts?tags=bonocho"
Get the direct URL of an image from a site supporting authentication
with username & password:
gallery-dl -g -u "<username>" -p "<password>" "https://twitter.com/i/web/status/604341487988576256"
Filter manga chapters by chapter number and language:
gallery-dl --chapter-filter "10 <= chapter < 20" -o "lang=fr" "https://mangadex.org/title/59793dd0-a2d8-41a2-9758-8197287a8539"
| Search a remote resource for URLs and download images from them:
| (URLs for which no extractor can be found will be silently ignored)
gallery-dl "r:https://pastebin.com/raw/FLwrCYsT"
If a site's address is nonstandard for its extractor, you can prefix
the URL with the extractor's name to force the use of a specific
extractor:
gallery-dl "tumblr:https://sometumblrblog.example"
Configuration
Configuration files for gallery-dl use a JSON-based file format.
Documentation
A list of all available configuration options and their descriptions can
be found in docs/configuration.rst.
| For a default configuration file with available options set to their
default values, see docs/gallery-dl.conf.
| For a commented example with more involved settings and option usage,
see docs/gallery-dl-example.conf.
Locations
gallery-dl searches for configuration files in the following places:
Windows:
: - %APPDATA%\gallery-dl\config.json
- %USERPROFILE%\gallery-dl\config.json
- %USERPROFILE%\gallery-dl.conf
(`%USERPROFILE%` usually refers to a user\'s home directory, i.e.
`C:\Users\<username>\`)
Linux, macOS, etc.:
: - /etc/gallery-dl.conf
- ${XDG_CONFIG_HOME}/gallery-dl/config.json
- ${HOME}/.config/gallery-dl/config.json
- ${HOME}/.gallery-dl.conf
When run as executable, gallery-dl will also
look for a gallery-dl.conf
file in the same directory as said
executable.
It is possible to use more than one configuration file at a time. In
this case, any values from files after the first will get merged into
the already loaded settings and potentially override previous ones.
Authentication
Username & Password
Some extractors require you to provide valid login credentials in the
form of a username & password pair. This is necessary for nijie
and
optional for aryion
, danbooru
, e621
, exhentai
, idolcomplex
,
imgbb
, inkbunny
, mangadex
, mangoxo
, pillowfort
, sankaku
,
subscribestar
, tapas
, tsumino
, twitter
, and zerochan
.
You can set the necessary information in your configuration
file
{
"extractor": {
"twitter": {
"username": "<username>",
"password": "<password>"
}
}
}
or you can provide them directly via the -u/--username
and
-p/--password
or via the -o/--option
command-line options
gallery-dl -u "<username>" -p "<password>" "URL"
gallery-dl -o "username=<username>" -o "password=<password>" "URL"
Cookies
For sites where login with username & password is not possible due to
CAPTCHA or similar, or has not been implemented yet, you can use the
cookies from a browser login session and input them into gallery-dl.
This can be done via the
cookies option in your
configuration file by specifying
-
| the path to a Mozilla/Netscape format cookies.txt file exported by
a browser addon
| (e.g. Get
cookies.txt
for Chrome, Export
Cookies
for Firefox) -
| a list of name-value pairs gathered from your browser's web
developer tools
| (in
Chrome,
in
Firefox) -
| the name of a browser to extract cookies from
| (supported browsers are Chromium-based ones, Firefox, and Safari)
For example:
{
"extractor": {
"instagram": {
"cookies": "$HOME/path/to/cookies.txt"
},
"patreon": {
"cookies": {
"session_id": "K1T57EKu19TR49C51CDjOJoXNQLF7VbdVOiBrC9ye0a"
}
},
"twitter": {
"cookies": ["firefox"]
}
}
}
| You can also specify a cookies.txt file with the --cookies
command-line option
| or a browser to extract cookies from with --cookies-from-browser
:
gallery-dl --cookies "$HOME/path/to/cookies.txt" "URL"
gallery-dl --cookies-from-browser firefox "URL"
OAuth
gallery-dl supports user authentication via
OAuth for some extractors. This
is necessary for pixiv
and optional for deviantart
, flickr
,
reddit
, smugmug
, tumblr
, and mastodon
instances.
Linking your account to gallery-dl grants it the ability to issue
requests on your account's behalf and enables it to access resources
which would otherwise be unavailable to a public user.
To do so, start by invoking it with oauth:<sitename>
as an argument.
For example:
gallery-dl oauth:flickr
You will be sent to the site's authorization page and asked to grant
read access to gallery-dl. Authorize it and you will be shown one or
more "tokens", which should be added to your configuration file.
To authenticate with a mastodon
instance, run gallery-dl with
oauth:mastodon:<instance>
as argument. For example:
gallery-dl oauth:mastodon:pawoo.net
gallery-dl oauth:mastodon:https://mastodon.social/