Master gallery-dl: 7 Powerful Config Tricks for 2025

Introduction: Beyond Basic Downloads

If you're a digital archivist, data hoarder, or content creator, you've likely encountered gallery-dl. This powerful command-line tool is the Swiss Army knife for downloading image and video galleries from hundreds of websites. While its basic usage is straightforward—gallery-dl <URL>—its true potential is unlocked within its configuration file. Simply put, a well-crafted gallery-dl.conf can transform a manual, repetitive task into a fully automated, intelligent archiving system.

As we move into 2025, websites are more complex and our archiving needs more sophisticated. It's time to graduate from basic commands and master the configuration file. This guide will walk you through seven powerful tricks that will elevate your gallery-dl usage from novice to expert, saving you time, improving organization, and future-proofing your digital collections.

Prerequisites for Power Usage

Before we dive in, this guide assumes you have a basic understanding of gallery-dl. You should know:

• How to install gallery-dl.
• How to run it from your terminal or command prompt.
• Where to find and create your configuration file (typically in ~/.config/gallery-dl/config.json on Linux/macOS or %APPDATA%\gallery-dl\config.json on Windows).

If you're new, we recommend running a few basic downloads first to get a feel for the tool. Now, let's unlock its power.

Trick 1: Dynamic Filenaming with Python Expressions

Static filenames are a thing of the past. gallery-dl allows you to use Python f-string expressions to create incredibly descriptive and organized filenames and paths on the fly.

The Code

{
  "extractor": {
    "path": "{category}/{author[name]}/{date:%Y-%m} {title}",
    "filename": "{date:%Y-%m-%d}_{index}_{filename}.{extension}"
  }
}

The Breakdown

This config snippet automatically organizes downloads into a clean directory structure. For a file downloaded from a supported site, it might create a path like Art/AwesomeArtist/2025-01 My Cool Art/2025-01-15_001_original-filename.jpg.

• {category}: The category from the website (e.g., 'Art', 'Photography').
• {author[name]}: Accesses the 'name' key within the 'author' object. This is far more robust than just {author}.
• {date:%Y-%m}: Formats the post's date into a `YEAR-MONTH` format, perfect for monthly folders.
• {index}: The download number within the gallery, ensuring files are ordered correctly.

This level of dynamic organization is the foundation of a scalable digital archive.

Trick 2: Conditional Configuration with Profiles

Do you sometimes want a quick download, and other times a full archival backup with metadata? Instead of juggling multiple config files, use profiles. Profiles are named configuration sets you can invoke from the command line.

The Code

{
  "profiles": {
    "quick": {
      "-o": "skip-metadata=true",
      "-o": "write-tags=false",
      "-o": "videos=false"
    },
    "archive": {
      "-o": "write-metadata=true",
      "-o": "write-description=true",
      "-o": "videos=true",
      "postprocessors": [ { "name": "metadata" } ]
    }
  }
}

The Breakdown

With this config, you can now run specialized commands:

• gallery-dl -p quick <URL>: Downloads only images, skipping all metadata for a fast grab.
• gallery-dl -p archive <URL>: Downloads everything, including videos, and writes a comprehensive metadata JSON file for each item.

Profiles keep your base configuration clean while giving you immense flexibility for different tasks.

Trick 3: Advanced Post-Processing with 'exec'

The built-in post-processors are great, but the exec post-processor is your gateway to limitless automation. It allows you to run any command-line script after a file is downloaded.

The Code

{
  "postprocessors": [
    {
      "name": "exec",
      "command": ["exiftool", "-overwrite_original", "-artist={author[name]}", "-description={description}", "{_path}"]
    },
    {
      "name": "exec",
      "for": "category == 'video'",
      "command": ["ffmpeg", "-i", "{_path}", "-vf", "scale=1280:-1", "-c:v", "libx264", "{_path|stem}_720p.mp4"]
    }
  ]
}

The Breakdown

• Exiftool Integration: The first command uses exiftool to embed the author's name and the post's description directly into the image file's EXIF data. {_path} is a special variable that refers to the downloaded file's full path.
• Conditional Video Re-encoding: The second command is even smarter. Using "for": "category == 'video'", it only runs for videos. It then uses ffmpeg to create a 720p version of the downloaded video, which is perfect for creating smaller proxy files for quick viewing.

Trick 4: Centralized & Secure Credentials

Never hardcode your usernames and passwords directly in your main config file. It's a security risk. gallery-dl supports using a classic .netrc file for credentials.

The Code

First, enable it in your config.json:

{
  "extractor": {
    "netrc": true
  }
}

Then, create a .netrc file (or _netrc on Windows) in your home directory with strict permissions (chmod 600 ~/.netrc):

machine example.com
  login myusername
  password mysecretpassword

machine another-site.net
  login myotheruser
  password myothersecret

The Breakdown

Now, when gallery-dl needs to log into `example.com`, it will automatically and securely pull the credentials from your .netrc file. This separates your sensitive data from your operational configuration, which is a critical security best practice. It also allows you to back up your gallery-dl config to a private Git repository without exposing your passwords.

Trick 5: Bending the Web with Custom URL Rewrites

The rewrite option is a hidden gem for creating shortcuts or handling URLs from sites gallery-dl doesn't officially support. It allows you to transform a URL before the extractor processes it.

The Code

{
  "rewrites": {
    "~favs": "https://www.example.com/users/myusername/favorites?page={}",
    "(https?://)m\\.(somesite\\.com/.+)": "\\1\\2"
  }
}

The Breakdown

• Alias/Shortcut: The first rule creates a custom alias. Now, you can simply run gallery-dl ~favs:1 to download page 1 of your favorites, which is much easier to type and remember than the full URL. The {} is a placeholder for any arguments you pass after the colon.
• Mobile-to-Desktop Redirect: The second rule uses a regular expression to automatically convert mobile URLs (like `m.somesite.com`) to their desktop equivalent (`somesite.com`), which often works better with gallery-dl's extractors. This saves you the step of manually editing URLs.

Trick 6: Smart Throttling and Polite Retries

Bombarding a server with rapid-fire requests is a quick way to get your IP address temporarily blocked. Being a good internet citizen means using rate limits and intelligent retries.

The Code

{
  "downloader": {
    "retries": 5,
    "retry-sleep": 30,
    "rate-limit": "2M"
  },
  "extractor": {
    "rate-limit": 10,
    "rate-limit-sleep": 5
  }
}

The Breakdown

This config separates limits for the two main phases of gallery-dl's operation:

• downloader: This section controls the actual file downloads. "rate-limit": "2M" caps the download speed at 2 MB/s. "retries": 5 will attempt a failed download up to 5 times, waiting 30 seconds between each attempt.
• extractor: This controls the API calls used to find the files. "rate-limit": 10 and "rate-limit-sleep": 5 tells gallery-dl to make at most 10 API requests every 5 seconds. This is crucial for avoiding API bans on sensitive sites.

Trick 7: The Master Archive Log for Flawless Collections

For large-scale archiving, you need a system to track what you've already downloaded. Combining an `input-file` with an `archive` file is the professional way to do it.

The Code

First, enable the archive file in your config.json:

{
  "extractor": {
    "archive": "~/gallery-dl-archive.txt"
  }
}

Next, create a text file, say my-sites.txt, with a list of all the URLs you want to monitor:

https://www.example.com/users/artist1
https://www.somesite.net/tags/landscape
# This is a comment, it will be ignored
https://www.example.com/users/artist2/favorites

The Breakdown

You can now run a single command to update your entire collection: gallery-dl --input-file my-sites.txt.

Here's how it works: gallery-dl reads each URL from my-sites.txt. Before downloading a file, it checks if that file's unique ID is present in gallery-dl-archive.txt. If it is, it skips it. If it's not, it downloads the file and then adds its ID to the archive file. This is the most robust way to prevent duplicates and efficiently update massive collections over time.

Configuration Strategy Comparison

Choosing the right approach depends on your needs. Here's a comparison of different levels of configuration:

Conclusion: Your Config, Your Superpower

Your gallery-dl configuration file is more than just a place for settings; it's a script for your personal archiving robot. By moving beyond the defaults and embracing dynamic filenaming, profiles, post-processing, and secure practices, you transform gallery-dl from a simple tool into the core of an intelligent, automated, and robust digital preservation workflow.

Take the time to implement these tricks. Start with one or two that solve your biggest pain points, and gradually build a configuration that perfectly suits your needs. The initial effort will pay for itself countless times over in saved time, better organization, and the peace of mind that comes with a well-managed archive.