How to Enter a Token in gallery-dl: Complete Authentication Guide for Reddit and Supported Sites

Authentication is one of the most useful gallery-dl features when you need to download media from an account you are legitimately authorized to use. Whether you are archiving your own posts, saving approved project assets, or accessing a community where your account already has permission, gallery-dl can use supported authentication methods such as OAuth refresh tokens, API credentials, and session-based login data.

This complete guide explains how to enter a token in gallery-dl, how Reddit authentication works, how to create a Reddit API app, where to add your token in the gallery-dl configuration file, how to test it, and how to fix common authentication errors.

Important: Authentication proves access; it does not create permission. Use gallery-dl only for media you own or are clearly allowed to download. Do not use tokens, cookies, or scripts to bypass private communities, paywalls, creator restrictions, age gates, DRM, or other access controls.

Quick Answer: How to Enter a Token in gallery-dl

For Reddit, the recommended process is:

1. Create your own Reddit installed app.
2. Add its client ID and OAuth user agent to your gallery-dl configuration file.
3. Run:

gallery-dl oauth:reddit

4. Complete the official Reddit authorization flow.
5. Let gallery-dl save and use the refresh token for your authorized account.

gallery-dl documents Reddit OAuth support through client-id, user-agent-oauth, and refresh-token configuration options.

What Is a gallery-dl Authentication Token?

A token is a sensitive authentication credential that lets software make approved requests on behalf of an account. In gallery-dl, the exact token type depends on the website you are using.

For example, a Reddit setup may use:

• A client ID that identifies your Reddit application.
• A user agent that identifies your software request.
• A refresh token that links gallery-dl to your authorized Reddit account.
• A short-lived access token generated automatically when needed.

These values serve different purposes. Your client ID identifies the app, while a refresh token authenticates your own approved account session. Never confuse either with a public download link.

When Do You Need a Token in gallery-dl?

You may not need authentication for many public pages. gallery-dl can often process publicly available URLs without requiring a sign-in.

However, authentication may be useful when:

• You are downloading content from your own account.
• You need access to a community where your account has already been approved.
• A supported service requires its official API for specific account features.
• You are reaching rate limits and need to use your own authorized API configuration.
• You want a more reliable workflow for your legitimate personal archive.

A token does not give you additional rights. If you cannot access a page normally with your own account, gallery-dl should not be used to work around that restriction.

Understanding Reddit Authentication in gallery-dl

gallery-dl supports two general Reddit API approaches:

Method	What It Uses	Best For
REST API	Standard requests and supported session data	Public browsing and basic use
OAuth API	Client ID, user agent, and refresh token	Authorized account-based Reddit access

When a Reddit client ID is configured, gallery-dl can use Reddit’s OAuth API. The official documentation states that OAuth requires a client ID, OAuth user agent, and refresh token for authentication.

For most users, the simplest and most secure option is to let gallery-dl guide you through the OAuth authorization flow instead of obtaining or copying random tokens manually.

Before You Start: Install and Update gallery-dl

Install or update gallery-dl before configuring authentication:

python -m pip install -U gallery-dl

On Windows, you can also use:

py -m pip install -U gallery-dl

Confirm that the program is available:

gallery-dl --version

Keeping gallery-dl updated matters because websites and APIs can change over time. An older version may produce authentication errors even when your credentials are correct.

Step 1: Create a Reddit App for gallery-dl

To authenticate Reddit safely, create an API app under the Reddit account you own.

1. Sign in to Reddit using your own account.
2. Open the apps section in Reddit account preferences.
3. Select the option to create a new app.
4. Give the app a clear name, such as my-gallery-dl-app.
5. Choose installed app as the app type.
6. Set the redirect URI to:

http://localhost:6414/

7. Complete the form and create the app.
8. Copy the client ID shown under your app name.

gallery-dl’s official documentation specifically instructs users to choose “installed app” and use http://localhost:6414/ as the redirect URI for Reddit OAuth configuration.

What Is the Reddit Client ID?

The client ID is a short identifier for the app you created. It tells Reddit which application is requesting authentication.

Do not use a client ID copied from an untrusted forum, video description, or random GitHub file. Creating your own app is more reliable and gives you control over your own configuration.

Step 2: Create a Proper Reddit OAuth User Agent

Reddit expects API requests to identify the application through a user-agent string. gallery-dl recommends a structure like this:

Python:my-gallery-dl-app:v1.0 (by /u/your-reddit-username)

Replace:

• my-gallery-dl-app with your app name.
• your-reddit-username with your actual Reddit username.

For example:

Python:galleryarchive:v1.0 (by /u/exampleuser)

A clear user agent helps you follow Reddit API conventions and makes your own setup easier to recognize later.

Step 3: Add Reddit Details to the gallery-dl Configuration File

gallery-dl uses JSON configuration files. Its configuration system supports general options, website-specific options, and extractor-specific settings.

Add the following structure to your configuration file:

{
  "extractor": {
    "reddit": {
      "client-id": "YOUR_REDDIT_CLIENT_ID",
      "user-agent-oauth": "Python:my-gallery-dl-app:v1.0 (by /u/your-reddit-username)"
    }
  }
}

Replace the placeholder values with your own app information.

Example Reddit Configuration

Here is a complete example using sample values:

{
  "extractor": {
    "reddit": {
      "client-id": "abc123yourclientid",
      "user-agent-oauth": "Python:galleryarchive:v1.0 (by /u/exampleuser)"
    }
  }
}

Do not copy the sample client ID. It is only an example of the formatting.

Step 4: Generate the Reddit Refresh Token

Once your client ID and user agent are saved, open Command Prompt, PowerShell, or Terminal and run:

gallery-dl oauth:reddit

gallery-dl will begin the authorization process. Sign in only through Reddit’s official authorization page, verify that you are using your own account, and approve access only if you understand the request.

After successful authorization, gallery-dl obtains a refresh token associated with your Reddit app and account. The project documentation identifies gallery-dl oauth:reddit as the method for getting a refresh token for a Reddit client ID.

Step 5: How to Enter a Refresh Token Manually

Automatic OAuth authorization is the preferred method. But if you already have a valid refresh token that was generated for your own Reddit app and account, you can add it to your configuration file.

{
  "extractor": {
    "reddit": {
      "client-id": "YOUR_REDDIT_CLIENT_ID",
      "user-agent-oauth": "Python:my-gallery-dl-app:v1.0 (by /u/your-reddit-username)",
      "refresh-token": "YOUR_OWN_REFRESH_TOKEN"
    }
  }
}

The setting name is:

extractor.reddit.refresh-token

Never publish the token itself. If you expose it, treat it as compromised and replace it through the official authorization process.

How to Test Your gallery-dl Authentication

After you finish the configuration, test it with a public Reddit post that you own or are allowed to archive:

gallery-dl "https://www.reddit.com/r/example/comments/POST_ID/example-post/"

Use a real, complete URL in place of the example.

A successful test confirms that:

• gallery-dl is installed correctly.
• Your configuration file can be read.
• The Reddit URL is supported.
• Your account authorization is working when required.
• Your download directory is functioning as expected.

Start with one post before processing multiple pages. This makes troubleshooting much easier.

How to Set a Download Folder

You can choose the destination folder for one download by using -D:

gallery-dl -D "~/Downloads/gallery-dl" "https://www.reddit.com/r/example/comments/POST_ID/example-post/"

On Windows, use a path such as:

gallery-dl -D "C:\Users\YourName\Downloads\gallery-dl" "https://www.reddit.com/r/example/comments/POST_ID/example-post/"

You can also set a default base directory in your configuration:

{
  "extractor": {
    "base-directory": "~/Downloads/gallery-dl",
    "reddit": {
      "client-id": "YOUR_REDDIT_CLIENT_ID",
      "user-agent-oauth": "Python:my-gallery-dl-app:v1.0 (by /u/your-reddit-username)"
    }
  }
}

gallery-dl documents extractor.*.base-directory as the setting used for all download destinations.

Common gallery-dl Token Errors and Fixes

Error: Invalid token or authentication failed

This can happen when the refresh token is expired, revoked, copied incorrectly, or linked to a different app.

Fix it by running:

gallery-dl oauth:reddit

Then complete authorization again with your own Reddit account.

Error: Wrong client ID

Make sure the client ID in your configuration is from the exact Reddit app connected to your token. Do not use a client ID from another account or unrelated app.

Error: User agent is missing or incorrect

Check your user-agent-oauth value. It should clearly identify your application and Reddit username.

Use this format:

Python:application-name:v1.0 (by /u/your-reddit-username)

Error: Old authentication details are cached

If you changed your Reddit app settings or generated a new token, clear Reddit’s saved gallery-dl cache:

gallery-dl --clear-cache reddit

Then authorize again:

gallery-dl oauth:reddit

gallery-dl’s official Reddit setup instructions recommend clearing cached access-token entries after changing the client ID.

Error: The content is still unavailable

Authentication does not override website permissions. Confirm that your account is actually authorized to access the content through Reddit itself.

If a subreddit is private, restricted, deleted, quarantined, or otherwise unavailable to your account, do not attempt to bypass that restriction.

How to Keep Your Token Secure

Your gallery-dl token should be handled as private account data.

Follow these security practices:

• Never post a refresh token in a comment, Discord message, tutorial, or screenshot.
• Do not upload your configuration file to a public GitHub repository.
• Avoid saving tokens in shared folders or public cloud documents.
• Use separate local configuration files for personal and work accounts where appropriate.
• Remove old credentials when you stop using an account.
• Reauthorize through official channels if you believe a token was exposed.
• Do not use tokens supplied by another person.

A token is not just a technical string—it represents access tied to an account. Protect it accordingly.

gallery-dl Authentication Best Practices

A reliable gallery-dl workflow should be simple, authorized, and easy to maintain.

• Use your own Reddit account and API app.
• Use the automatic OAuth command whenever possible.
• Keep gallery-dl updated.
• Test one approved URL before downloading a collection.
• Use a dedicated download folder for archives.
• Keep source URLs for research, attribution, and recordkeeping.
• Respect Reddit rules, creator rights, and local copyright laws.
• Do not treat a valid token as permission to redistribute someone else’s media.

FAQ: Entering Tokens in gallery-dl

Conclusion

To enter a token in gallery-dl, use the official authentication method for the supported website. For Reddit, create your own installed app, add the client ID and user agent to your gallery-dl configuration, and run gallery-dl oauth:reddit to create an authorized refresh-token connection.

This method is safer, more reliable, and easier to maintain than manually copying unknown credentials. Use Gallery-DL responsibly, keep your token private, and download only content you have permission to save.

Latest Post:

• Domain Lookup: How to Check Domain Availability, Ownership, and Details
• How to Pause gallery-dl: Stop, Resume, and Manage Interrupted Downloads
• How to Use gallery-dl GitHub: Install, Update, and Run gallery-dl from the Official Project
• How to Use gallery-dl for Bunkr: Download Public and Authorized Files Safely
• How to Use gallery-dl for Flickr: Download Photos, Albums, and Your Authorized Media