How to Use gallery-dl

Confirm installation with gallery-dl --version. Find the canonical URL for one public post, profile, gallery, album, or collection that appears in the supported-sites list. Quote the URL so shell characters such as ampersands and question marks are not interpreted as operators. Add --simulate for the first run; gallery-dl will extract information without downloading files.

If simulation recognizes the extractor, remove --simulate and run the same command. Watch the first few output paths before launching a large profile. A successful one-off command establishes that installation, URL recognition, network access, and basic extractor behavior are working. Only then add authentication or permanent configuration.

gallery-dl --simulate "https://www.example.com/gallery"

gallery-dl "https://www.example.com/gallery"

gallery-dl -E "https://www.example.com/gallery"

The --destination option sets a base location for downloads. The exact subdirectories and filenames can still come from extractor defaults or configuration. Use --directory only when you want an exact target directory. On Windows, quote paths that contain spaces and remember that JSON configuration requires escaped backslashes; forward slashes are often easier to read in JSON paths.

Do not test folder rules on a huge timeline. Use a small range or simulation, inspect the generated path, and confirm that the filename contains stable identifiers. A readable filename is useful, but an archive ID is the stronger mechanism for preventing duplicates across renamed or moved files.

Some supported capabilities require an authenticated browser session. The --cookies-from-browser option reads cookies from a supported local browser profile; it does not require copying raw values into the shell. Specify the browser and, when necessary, its domain or profile selector. If the browser locks its cookie database, close it completely or test another supported browser profile you control.

Authentication does not grant rights you do not already have. It should only let gallery-dl access pages that your account is authorized to view. Do not use someone else's cookie file, upload cookies to this site, or commit authentication data to a repository. If a session expires, sign in through the normal browser flow and regenerate local access rather than searching for shared tokens.

gallery-dl --cookies-from-browser firefox "URL"

gallery-dl --cookies-from-browser chrome "URL"

gallery-dl --cookies "cookies.txt" "URL"

A download archive records IDs for successful downloads and skips matching items on later runs. Use it for recurring profiles, favorites, galleries, and scheduled jobs. Keep the archive file stable; rewriting its format or pointing different unrelated extractors at a carelessly shared archive can make behavior harder to reason about.

Ranges limit indexes, while --date-after and --date-before limit posts when the extractor exposes date metadata. A file filter evaluates a Python-style expression against available metadata. Always inspect fields with -K and test filters using --simulate. A copied filter can silently exclude everything when its assumed field is absent or has a different type.

gallery-dl --download-archive "archive.sqlite3" "URL"

gallery-dl --range "1-50" "URL"

gallery-dl --date-after 2026-01-01 --date-before 2026-07-01 "URL"

gallery-dl --write-metadata "URL"

Keep experimental values on the command line because they are easy to see and remove. Move stable choices such as the base directory, filename pattern, archive file, browser cookie source, and request delay into configuration after several successful tests. gallery-dl can merge more than one configuration file, so remember that later values may override earlier ones.

Use gallery-dl --config-status to inspect configuration status and --config-open when supported to open the active file. If behavior differs from the command you can see, test with --config-ignore. That one comparison quickly reveals whether an older default or site-specific configuration is responsible.

gallery-dl --config-status

gallery-dl --config-open

gallery-dl --config-ignore --simulate "URL"

How to use gallery-dl safely becomes easier when every new job follows the same small-test routine. Confirm the version, use a canonical public URL, simulate extraction, inspect the output path, and then download a limited range. This approach shows how to use gallery-dl without letting an unfamiliar filter, archive, filename rule, or cookie source affect thousands of items.

How to use gallery-dl for recurring jobs is equally systematic: keep one reviewed config, one stable archive, and one documented installation channel for each environment. Note the URL type and authentication method rather than storing secret values in a script. If results change, repeat the clean simulation before editing defaults. That is how to use gallery-dl as a predictable local tool instead of treating every failure as a new command experiment.