GALLERY-DL(1)

📦
version 1.32.14 · 8 versions
, in ubuntu stonking

okay bestie, sit down, hydrate, and let me tell you about the single most iconic lil command line tool in the whole image-hoarding ecosystem 💖

🌸 NAME 🌸

gallery-dl — download image-galleries and -collections

🦋 SYNOPSIS 🦋

gallery-dl [OPTION]... URL...

💅 DESCRIPTION 💅

okay so gallery-dl is a command-line program that downloads image-galleries and -collections from several image hosting sites. the way it's cross-platform, has so many configuration options, and has genuinely powerful filenaming capabilities?? it's giving main character energy, no cap 😭✨

🎀 OPTIONS 🎀

  • -h, --help — prints this help message and then dips out
  • --version — prints the program version and exits, periodt
  • -f, --filename FORMAT — the filename format string for your downloaded files (use '/O' if you want the "original" filenames, iykyk)
  • -d, --destination PATH — where your files go, the target location for file downloads
  • -D, --directory PATH — the exact location for file downloads, no wiggle room
  • --restrict-filenames VALUE — replaces restricted filename characters with underscores. pick one of 'windows', 'windows+', 'unix', 'ascii', 'ascii+', or bring your own custom set of characters 💫
  • --windows-filenames — forces filenames to be Windows-compatible, whether they like it or not
  • -X, --extractors PATH — load external extractors from PATH
  • --compat — restores the legacy 'category' names, for the nostalgia girlies
  • -S, --server — enables server mode. sends input URLs to a gallery-dl server, or creates an IPC server when you give it no input URLs
  • -U, --update-check — checks if a newer version is available (spoiler: maybe 👀)
  • -i, --input-file FILE — downloads all the URLs found in FILE (use '-' for stdin). and yes bestie, you can specify more than one --input-file
  • -I, --input-file-comment FILE — downloads the URLs found in FILE, then comments them out once they've downloaded successfully. tidy!!
  • -x, --input-file-delete FILE — downloads the URLs found in FILE, then deletes them after they downloaded successfully. ruthless 💀
  • --no-input — does not prompt for passwords/tokens
  • -q, --quiet — activates quiet mode 🤫
  • -w, --warning — prints only warnings and errors
  • -v, --verbose — prints various debugging information, the tea ☕
  • -g, --get-urls — prints the URLs instead of downloading
  • -G, --resolve-urls — prints URLs instead of downloading, and resolves intermediary URLs on the way
  • -j, --dump-json — prints JSON information
  • -J, --resolve-json — prints JSON information, and resolves intermediary URLs too
  • -s, --simulate — simulates data extraction, downloads absolutely nothing
  • -E, --extractor-info — prints extractor defaults and settings
  • -K, --list-keywords — prints a list of available keywords plus example values for the URLs you gave it
  • -e, --error-file FILE — adds input URLs that returned an error to FILE
  • -N, --print [EVENT:]FORMAT — writes FORMAT during EVENT to standard output instead of downloading files. EVENT defaults to 'prepare'. can be used multiple times. examples: 'id' or 'post:{md5[:8]}'
  • --Print [EVENT:]FORMAT — like --print, but it downloads files as well (capital P, capital energy 👑)
  • --print-to-file [EVENT:]FORMAT FILE — appends FORMAT during EVENT to FILE instead of downloading files. can be used multiple times
  • --Print-to-file [EVENT:]FORMAT FILE — like --print-to-file, but it downloads files as well
  • --list-modules — prints a list of available extractor modules
  • --list-extractors [CATEGORIES] — prints a list of extractor classes with description, (sub)category and example URL
  • --write-log FILE — writes logging output to FILE
  • --write-unsupported FILE — writes URLs that get emitted by other extractors but can't be handled to FILE
  • --write-pages — writes downloaded intermediary pages to files in the current directory so you can debug problems
  • --print-traffic — displays sent and read HTTP traffic
  • --no-colors — does not emit ANSI color codes in output 🚫🌈
  • -R, --retries N — maximum number of retries for failed HTTP requests, or -1 for infinite retries (default: 4)
  • -a, --user-agent UA — the User-Agent request header
  • --http-timeout SECONDS — timeout for HTTP connections (default: 30.0)
  • --proxy URL — use the specified proxy
  • --xff VALUE — uses a fake 'X-Forwarded-For' HTTP header to try bypassing geographic restrictions. can be IP blocks in CIDR notation or two-letter ISO 3166-2 country codes (12.0.0.0/8,FR,CN)
  • --source-address IP — client-side IP address to bind to
  • -4, --force-ipv4 — makes all connections via IPv4
  • -6, --force-ipv6 — makes all connections via IPv6
  • --no-check-certificate — disables HTTPS certificate validation
  • -r, --limit-rate RATE — maximum download rate (e.g. 500k, 2.5M, or 800k-2M)
  • --chunk-size SIZE — size of in-memory data chunks (default: 32k)
  • --no-part — does not use .part files
  • --no-skip — does not skip downloads, it overwrites existing files
  • --no-mtime — does not set file modification times according to Last-Modified HTTP response headers
  • --no-download — does not download any files
  • --sleep SECONDS — number of seconds to wait before each download. can be a constant value or a range (e.g. 2.7 or 2.0-3.5)
  • --sleep-skip SECONDS — number of seconds to wait after skipping a file download
  • --sleep-extractor SECONDS — number of seconds to wait before starting data extraction for an input URL
  • --sleep-request SECONDS — number of seconds to wait between HTTP requests during data extraction
  • --sleep-retries [TYPE=]SECONDS — number of seconds to wait before retrying an HTTP request. can be prefixed with 'lin[:START[:MAX]]' or 'exp[:BASE[:START[:MAX]]]' for linear or exponential growth between consecutive retries (e.g. '30', 'exp=40', 'lin:20=30-60'
  • --sleep-429 [TYPE=]SECONDS — number of seconds to wait when receiving a '429 Too Many Requests' response
  • -o, --option KEY=VALUE — additional options. example: -o browser=firefox
  • -c, --config FILE — additional configuration files in default format
  • --config-json FILE — additional configuration files in JSON format
  • --config-yaml FILE — additional configuration files in YAML format
  • --config-toml FILE — additional configuration files in TOML format
  • --config-type TYPE — sets the filetype of default configuration files (json, yaml, toml)
  • --config-ignore — does not load default configuration files
  • --config-create — creates a basic configuration file
  • --config-status — shows configuration file status
  • --config-open — opens configuration file in an external application
  • --cache-file PATH — use PATH as the cache file
  • --cache-status — shows cache file information
  • --cache-show MODULE — shows cached values for MODULE (ALL to show all entries, EXP to show only expired entries, VAL to show only valid entries)
  • --cache-clear MODULE — deletes cached login sessions, cookies, etc. for MODULE (ALL to delete everything, EXP to delete only expired values)
  • --cache-vacuum — cleans up the cache database by removing unused space and reorganizing the data to improve performance. self-care for your cache 🧖
  • -u, --username USER — the username to login with
  • -p, --password PASS — the password belonging to the given username
  • --netrc — enables .netrc authentication data
  • -C, --cookies FILE — file to load additional cookies from 🍪
  • --cookies-export FILE — exports session cookies to FILE
  • --cookies-from-browser BROWSER[/DOMAIN][+KEYRING][:PROFILE][::CONTAINER] — name of the browser to load cookies from, with an optional domain prefixed with /, keyring name prefixed with +, profile prefixed with :, and container prefixed with :: ('none' for no container (default), 'all' for all containers)
  • -A, --abort N[:TARGET] — stops the current extractor(s) after N consecutive file downloads were skipped. specify a TARGET to set how many levels to ascend or which subcategory to jump to. examples: '-A 3', '-A 3:2', '-A 3:manga'
  • -T, --terminate N — stops the current & parent extractors and proceeds with the next input URL after N consecutive file downloads were skipped
  • --filesize-min SIZE — does not download files smaller than SIZE (e.g. 500k or 2.5M)
  • --filesize-max SIZE — does not download files larger than SIZE (e.g. 500k or 2.5M)
  • --download-archive FILE — records successfully downloaded files in FILE and skips downloading any file that's already in it. memory of an elephant fr fr 🐘
  • --date-before DATE — processes only posts created before this date, given in ISO 8601 format or as a Unix timestamp (e.g. '2025-10-31', '2026-01-09T15:30:00', '1767972600')
  • --date-after DATE — processes only posts created after this date. stops extraction when an older post is encountered
  • --blacklist CATEGORIES — ignores the given comma-separated category names or category:subcategory pairs when spawning child extractors for external URLs (e.g. 'pixiv', 'pixiv:user,*:artist')
  • --whitelist CATEGORIES — allows only the given comma-separated category names or category:subcategory pairs when spawning child extractors for external URLs
  • --tags-blacklist TAGS — ignores posts tagged with any of the tags given as a comma-separated list or as a path to a file containing them. Danbooru blacklist rules are supported. can be '/import' to use your account's blacklist. (e.g. '1girl', 'shirt,highres -blush,smile', 'C:athot.txt')
  • --tags-whitelist TAGS — allows only posts tagged with at least one of the tags given as a comma-separated list or a path to a file containing them
  • --range RANGE — index range(s) specifying which files to download. these can be a constant value, a range, or a slice (e.g. '5', '8-20', or '1:24:3')
  • --post-range RANGE — like '--range', but for posts
  • --child-range RANGE — like '--range', but for child extractors handling manga chapters, external URLs, etc.
  • --filter EXPR — a Python expression controlling which files to download. files for which the expression evaluates to False are ignored. the available keys are the filename-specific ones listed by '-K'. example: --filter "image_width >= 1000 and rating in ('s', 'q')"
  • --post-filter EXPR — like '--filter', but for posts
  • --child-filter EXPR — bestie it's literally --filter but for the child extractors, you know, the ones doing manga chapters and external URLs and all that extracurricular 💅
  • -P, --postprocessor NAME — turn on the post processor you named, go off queen ✨
  • --no-postprocessors — nope, not a single post processor runs today, we're resting 🛌
  • -O, --postprocessor-option KEY=VALUE — extra options for your post processors, pass them a little something 🎀
  • --write-metadata — drops your metadata into separate JSON files, one per file, very organized of it ✨
  • --write-info-json — writes the whole gallery metadata into an info.json file 📝
  • --write-tags — image tags go into their own separate text files, cute and labelled 🏷️
  • --zip — shove all the downloaded files into a ZIP archive 🗜️
  • --cbz — same energy but a CBZ archive, comic reader girlies rise 🔥
  • --mtime NAME — sets file modification times based on whatever metadata NAME picks out. Like 'date' or 'status[date]' 👑
  • --rename FORMAT — renames files you already downloaded, going from FORMAT to whatever the current filename format is 🔄
  • --rename-to FORMAT — opposite direction bestie: from the current filename format over to FORMAT 💫
  • --ugoira FMT — converts Pixiv Ugoira to FMT using FFmpeg. The supported formats are 'webm', 'mp4', 'gif', 'vp8', 'vp9', 'vp9-lossless', 'copy', 'zip' — that's the whole list, no more, no less 🎬
  • --exec CMD — runs CMD for every single downloaded file. The replacement fields you can use are {} or {_path}, {_temppath}, {_directory, {_filename} — wait no, it's {_directory}, {_filename} ok phew 😭. On Windows, use {_path_unc} or {_directory_unc} for UNC paths. Example: --exec "convert {} {}.png && rm {}" 💻
  • --exec-after CMD — runs CMD after all the files are downloaded. Example: --exec-after "cd {_directory} && convert * ../doc.pdf" 🎉

🌸 EXAMPLES 🌸

So here's what it actually looks like in the wild, bestie:

  • gallery-dl URL — downloads images from that URL. That's it. That's the whole vibe 💖
  • gallery-dl -g -u <username> -p <password> URL — prints the direct URLs from a site that needs you to log in first 🔐
  • gallery-dl --filter 'type == "ugoira"' --range '2-4' URL — stacks a filter AND a range expression together. This one only downloads the second, third, and fourth file where the type value equals "ugoira" ✨
  • gallery-dl r:URL — scans that URL for other URLs and then invokes gallery-dl on each one it finds. Recursive queen 🌀
  • gallery-dl oauth:SITE-NAME — gets you OAuth authentication tokens for deviantart, flickr, reddit, smugmug, and tumblr. Five sites, one little command, iconic 👑

📁 FILES 📁

The places it keeps its stuff:

  • /etc/gallery-dl.conf — the system wide configuration file. Everybody shares this one 🏫
  • ~/.config/gallery-dl/config.json — your own personal per user configuration file 💁‍♀️
  • ~/.gallery-dl.conf — the alternate per user configuration file, for when you're feeling different 🌈

💀 BUGS 💀

Found something broken? Not me being dramatic but please tell the devs, they want to know fr fr:

👑 AUTHORS 👑

🔗 SEE ALSO 🔗

okay that's the whole page, you made it to the end, I'm so proud of you 🥹 this was GALLERY-DL(1), version 1.32.14, dated 2026-09-27 — screenshot it, bookmark it, tattoo it, whatever, just remember it 💖 now go download something gorgeous, mwah 💅✨

📦 where this page comes from