gallery-dl Config Generator

Configuration locations differ by operating system and installation context. Common user paths include gallery-dl.conf in a Windows user application-data folder and gallery-dl/gallery-dl.conf under an XDG config directory on Linux. macOS and other Unix-like systems may use user config directories documented by the project. The authoritative answer is the status reported by your own executable.

A config file is JSON despite the .conf extension. Save it as plain UTF-8 text, keep keys and string values in double quotes, remove trailing commas, and escape backslashes when you use Windows-style paths. Forward slashes in Windows JSON paths are often easier to read. Run a JSON validator or use this generator before blaming an extractor for a parse error.

gallery-dl --config-status

gallery-dl --config-open

gallery-dl --config "C:/path/gallery-dl.conf" --simulate "URL"

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

Most general download defaults belong under the extractor object. A broad extractor section can set a base directory, filename pattern, archive database, cookies source, and request timing. Site-specific sections can override those defaults, but add them only after checking the exact configuration key and extractor name in official documentation.

Configuration is powerful because it runs on every matching request. That also makes broad changes risky. A filename expression copied for one extractor may refer to fields another extractor does not expose. A global filter can silently remove valid items. Begin with output location and archive settings, test multiple representative URLs, and introduce formatting or filtering only when -K confirms the required fields.

{
  "extractor": {
    "base-directory": "./gallery-dl/",
    "archive": "./gallery-dl/archive.sqlite3"
  }
}

gallery-dl -K "URL"

A base directory gives downloads a predictable root. An archive prevents successful IDs from being downloaded repeatedly. Browser cookies can authenticate sites using a local profile, and a small sleep interval can reduce request bursts. Metadata, ZIP, and filename choices change storage behavior, so evaluate them with small test jobs.

Never paste raw cookie values, passwords, API secrets, or private URLs into a public config example. Keep local configuration outside shared repositories or add it to ignore rules. If you synchronize config between machines, use separate secret storage and confirm that paths, browser profiles, and file permissions make sense on each device.

First check that the JSON parses and --config-status reports the expected path. Simulate one public URL with the config, then simulate the same URL with --config-ignore. A difference between those results proves configuration is involved. Narrow the cause by commenting through a copy is not valid JSON; instead, remove one suspect key at a time from a temporary file.

When more than one config file is loaded, later or more specific values may override earlier defaults. Keep the setup small enough to understand. Record why each non-obvious option exists, maintain a known-good backup, and retest after upgrades because extractors, metadata fields, and supported options can evolve.

• Validate JSON syntax before testing network behavior.
• Confirm the loaded file with --config-status.
• Use --simulate on a small, representative public URL.
• Compare with --config-ignore to isolate configuration.
• Add site-specific overrides only after global defaults work.
• Keep cookies and secrets local and out of version control.

Keep gallery-dl config small enough to explain without reconstructing old experiments. Start with a base directory and archive, then add filename, cookies, timing, or postprocessor rules only after each option succeeds on representative URLs. A compact gallery-dl config is easier to compare with --config-ignore and less likely to apply an extractor-specific assumption globally.

Treat every gallery-dl config change like a small deployment. Validate the JSON, preserve a known-good copy, simulate a public URL, inspect the planned paths, and then test a limited download. If cookies are referenced, confirm only the selector or protected local filename is stored—not raw session values. If the config is shared between computers, review paths, operating-system filename rules, browser profiles, and permissions separately on each machine.

Document the reason for non-obvious keys beside the file in a secret-free note. Record which URLs were used for validation and which gallery-dl version passed. When an extractor update changes metadata, that record helps you distinguish a new upstream field from an accidental gallery-dl config override. Remove obsolete keys instead of leaving disabled-looking fragments, because JSON has no standard comment syntax and a copied pseudo-comment can make the whole file invalid.