MAKE DOWNLOADED FILES FINDABLE

gallery-dl Filename Templates: Names, Folders & Metadata

gallery-dl filename templates turn extractor metadata into predictable file names and directory paths. This guide shows how to discover the fields your URL exposes, build a small format string, handle platform restrictions, and verify the result before a large run.

Metadata-driven namesPortable folder plansSafe test workflow
Editorial illustration of a terminal sending metadata-driven files into organized folders
A filename template connects extractor fields to a repeatable local folder structure.
Short answer: inspect first, then format

Run gallery-dl -K "URL" to see the replacement keys exposed for that extractor. Use those keys in a short --filename or extractor.filename format string, and use extractor.directory for folder segments. Test with --simulate and a small URL before adding a permanent configuration. A key that works on one extractor is not automatically available on another.

START WITH THE OUTPUT

What gallery-dl filename templates control

A filename template is a format string that is evaluated when gallery-dl prepares a downloaded file. It can combine extractor metadata such as an ID, title, date, author, page number, or extension with separators that make the result easy to scan. The same idea applies to directories: each segment can be built from a metadata value, so a collection can be grouped by site, creator, or series.

A template changes local organization, not the URL or extractor decision. Keep the first pattern short, unique, readable, and valid on the machines that run the job.

DISCOVER THE REAL FIELDS

Use -K to inspect available replacement keys

The official configuration guide recommends the -K or --list-keywords option for a specific URL. It prints the directory and filename keywords together with example values. That output is the boundary for a safe template: it tells you what this extractor provides instead of what a different site, an old tutorial, or a guessed variable might provide.

Use an authorized URL and keep the inspection small. Handle authentication separately through the site's normal sign-in flow and local browser cookies. Never paste cookies or tokens into a template or shared log.

Editorial diagram of metadata fields being inspected and combined into a filename
The -K output is the field list to use when designing a template for one extractor.
List fields for one URL
gallery-dl -K "URL"
Preview extraction without downloading
gallery-dl --simulate "URL"
BUILD ONE READABLE NAME

Create a gallery-dl filename format

Start with a stable identifier and add only the fields you will use when browsing the folder. A pattern such as {category}_{id}_{title}.{extension} is easy to recognize, while a date-first pattern can make chronological exports easier to sort. The exact fields depend on the extractor, so confirm each one with -K before running it.

Use --filename for a one-off test. After simulation and a small real run, move the pattern into the matching extractor section in JSON. Deeper extractor settings can override general values.

Use readable separators and keep the extension at the end. Retain an identifier as a fallback when a post has no title.

One-off filename test
gallery-dl --filename "{category}_{id}_{title}.{extension}" --simulate "URL"
Extractor-specific config
{
  "extractor": {
    "example": {
      "filename": "{id}_{title}.{extension}"
    }
  }
}
Pattern ideaUseful whenCheck before keeping
{id}_{extension}Titles are missing or change oftenThe ID is present and unique for the extractor
{date}_{id}_{title}You browse exports chronologicallyThe date has a predictable value and format
{author}/{title}A creator owns a separate folderAuthor values are safe as path segments
{category}_{id}_{title}.{extension}Several sites share one rootCategory and extension are listed by -K
SEPARATE COLLECTIONS

Use directory templates for predictable folders

The extractor.directory option accepts a list of format strings. Each item becomes one path segment, and the segments are joined beneath the base directory. This makes a plan such as site, author, and collection explicit without hiding the structure inside a long filename.

Use directory templates when folders help your workflow. Test author or title fields for separators, reserved characters, and long values. Never put secrets or private account names in shared paths.

Group by site and author
{
  "extractor": {
    "example": {
      "directory": ["{category}", "{author}"],
      "filename": "{id}_{title}.{extension}"
    }
  }
}
HANDLE DIFFERENT MEDIA

Add conditional filename formats carefully

Configuration can map conditions to filename strings. Conditions run in order and the first true one wins; an empty-string entry or extractor default can provide a fallback. This helps when a collection mixes video and images.

Because conditions are harder to debug, add one at a time and test both matching and non-matching URLs. Keep the fallback clear and use only fields shown by -K.

Separate video names
{
  "extractor": {
    "example": {
      "filename": {
        "extension == 'mp4'": "{id}_video.{extension}",
        "": "{id}_{title}.{extension}"
      }
    }
  }
}
MAKE THE NAME PORTABLE

Check Windows, Linux, and macOS filename limits

A valid template can still produce an invalid path. Titles may include reserved characters or excessive length. gallery-dl offers Windows, Unix, ASCII, and custom restriction modes; choose one for the job's host and inspect the output.

For shared configs, use conservative separators and shallow folders. Test punctuation, missing titles, non-Latin names, and long values because the total path matters as well as the filename.

Editorial illustration of a filename passing a cross-platform safety checklist into operating system folders
Cross-platform validation checks characters, length, separators, and the final destination together.
Test caseWhy it mattersSafer response
Reserved punctuationWindows rejects some charactersUse a restriction mode and review the preview
Long titleThe full path can become too longPrefer {id} plus a shortened title
Missing fieldA guessed key can be empty or invalidUse -K and a fallback pattern
Non-Latin textThe filesystem and shell may differUse UTF-8 and test the target machine
PROVE THE RESULT

A safe gallery-dl filename template workflow

Choose a supported URL and run -K. Test a short pattern with --simulate, then download a small range to a temporary destination and inspect names and folders.

Repeat the test with another representative URL, including punctuation or a missing title when possible. Once it works, save the setting in a persistent config and record the tested command.

When behavior changes, use --config-status and compare with --config-ignore --simulate. Preserve a working config and change one rule at a time.

Clean comparison
gallery-dl --config-ignore --simulate "URL"
Check active configuration
gallery-dl --config-status
Small first run
gallery-dl --range "1-3" --filename "{id}_{title}.{extension}" "URL"
FIX THE SMALLEST LAYER

Troubleshoot empty, duplicate, or invalid names

Generic names can mean a missing field, a deeper override, or the wrong active config. Compare -K with the pattern, check --config-status, and run a clean simulation before adding keys.

Skipped or overwritten files are a separate selection problem. Templates do not replace --download-archive or compare file bytes. Keep an identifier and inspect URL, range, and filters before changing history.

The template prints blanks

Run -K for the exact URL, replace guessed fields, and keep a literal fallback during testing.

  • Confirm the extractor
  • Check active config
  • Test one field

The path is rejected

Shorten the pattern, remove reserved punctuation, and test on the job's target machine.

  • Review characters
  • Review path length
  • Test non-Latin values
Use authorized, reproducible tests

Filename templates organize local downloads. They do not bypass login, paywalls, rate limits, access controls, or a platform's rules. Test only URLs and media you are allowed to access and keep credentials out of commands and logs.

KEEP THE JOB MAINTAINABLE

The repeatable naming routine

Keep the template small and extractor-specific. Discover keys with -K, simulate, test a few edge cases, then store it at the narrowest config level. Document the pattern with its destination and tested command.

FAQ

gallery-dl Filename Templates FAQ

How do I see which fields gallery-dl supports in a filename?

Run gallery-dl -K "URL". The command lists directory and filename keywords with example values for that URL's extractor. Use those results as the source of truth for the template.

What is a simple gallery-dl filename format?

A short pattern such as {id}_{title}.{extension} is a useful starting point when those fields appear in -K output. Add a category or date only after the basic pattern works on a small run.

Can I create folders with gallery-dl metadata?

Yes. The extractor.directory option accepts a list of format strings, and each string becomes one directory segment beneath the base directory. Test author and title values because they can contain path separators or reserved characters.

Why does my filename template work on one site but not another?

Replacement keys depend on the extractor. Run -K for each URL and keep site-specific settings at the narrowest extractor level instead of assuming one site's fields are global.

How can I make gallery-dl filenames safe on Windows?

Use a Windows-compatible restriction mode, conservative separators, and a short pattern. Test reserved punctuation, long titles, missing values, and the complete path on the Windows machine that will run the job.

Does a filename template prevent duplicate downloads?

No. It only controls local names. Use a stable --download-archive file for repeat-run history and keep an identifier in the filename so you can inspect the result.

Authoritative references

Official gallery-dl configuration documentationOfficial gallery-dl command-line optionsgallery-dl source and issues
NEXT STEP

Related gallery-dl resources