Understanding the youtube-dl Configuration File System and Precedence Rules

youtube-dl reads configuration files in a strict hierarchy where command-line arguments override custom configs, which override system-wide and user-specific settings.

The ytdl-org/youtube-dl repository implements a layered configuration system that allows administrators and users to set persistent defaults while maintaining flexibility for per-invocation overrides. Understanding the youtube-dl configuration file system ensures predictable behavior when managing download options across different environments.

How youtube-dl Loads Configuration Files

The configuration loading logic resides in youtube_dl/options.py, specifically within the parseOpts() function. Rather than treating each source as a separate stage, youtube-dl concatenates all configuration sources into a single list before parsing.

According to lines 33-34 of options.py, the parser combines sources in this order:

opts, args = parser.parse_args(system_conf + user_conf + custom_conf + command_line_conf)

This concatenation approach means that later entries overwrite earlier ones following standard optparse behavior. The parser processes the combined list in a single pass, applying the final value encountered for any given option.

Configuration File Precedence Order

The youtube-dl configuration file system follows a five-tier hierarchy from lowest to highest priority:

1. Default values – Hard-coded defaults defined in the OptionParser construction
2. User-specific configuration – Located via XDG directories, Windows AppData, or legacy home directory paths
3. System-wide configuration – /etc/youtube-dl.conf on Unix-like systems
4. Custom configuration – File or directory specified via --config-location
5. Command-line arguments – Direct arguments passed to the executable

Because the parser concatenates these sources as system_conf + user_conf + custom_conf + command_line_conf, command-line arguments receive ultimate precedence, followed by custom configs, then system configs, and finally user configs.

User Configuration File Locations

The _readUserConf() function (lines 55-89 of youtube_dl/options.py) implements a platform-aware search strategy for user-specific configuration files. The function checks locations in the following order, returning the first existing file found:

XDG Base Directory Support

On Unix-like systems respecting the XDG specification:

• $XDG_CONFIG_HOME/youtube-dl/config
• $XDG_CONFIG_HOME/youtube-dl.conf

If XDG_CONFIG_HOME is unset, the fallback checks:

• ~/.config/youtube-dl/config
• ~/.config/youtube-dl.conf

Windows AppData Locations

On Windows systems where APPDATA is defined:

• %APPDATA%\youtube-dl\config
• %APPDATA%\youtube-dl\config.txt

Legacy Home Directory Fallbacks

If no XDG or Windows-specific locations exist, the function checks legacy paths:

• ~/youtube-dl.conf
• ~/youtube-dl.conf.txt

If none of these files exist, _readUserConf() returns an empty list, meaning no user-specific options are applied.

Controlling Configuration Loading

The parseOpts() function provides two primary mechanisms for bypassing or redirecting configuration file loading, processed early in the execution flow (lines 20-28 of youtube_dl/options.py).

Bypassing All Configuration Files

The --ignore-config flag prevents youtube-dl from reading both system-wide and user-specific configuration files. This flag can be set either:

• On the command line directly
• Inside the system configuration file (/etc/youtube-dl.conf) itself

When detected, the parser skips loading system_conf and user_conf, using only custom_conf (if specified) and command_line_conf.

Specifying Custom Configuration Locations

The --config-location PATH argument forces youtube-dl to load a specific configuration file or directory, bypassing the default lookup logic. The parser resolves the path to an absolute location and:

• If the path is a file, reads it directly
• If the path is a directory, looks for youtube-dl.conf inside that directory

If the specified location does not exist, youtube-dl aborts with an error before processing any downloads.

Practical Example: Testing Configuration Precedence

You can observe the configuration loading behavior programmatically using the parseOpts() function from youtube_dl/options.py. This example demonstrates how different sources combine and override each other:

import sys
from youtube_dl.options import parseOpts

# Simulate loading a custom config file alongside command-line arguments

custom_conf_args = ['--config-location', '/path/to/custom.conf']
command_args = ['--output', 'myfile.%(ext)s', '--ignore-errors']

# parseOpts accepts a list of arguments (overrideArguments)

parser, opts, args = parseOpts(custom_conf_args + command_args)

print('Effective options after parsing:')
print(f'Output template: {opts.outtmpl}')
print(f'Ignore errors: {opts.ignoreerrors}')

In this execution:

1. Options from /path/to/custom.conf load first
2. The --output and --ignore-errors arguments from command_args override any conflicting values from the custom file
3. The final opts object reflects the merged configuration with command-line arguments taking precedence

Summary

• youtube-dl loads configuration through a concatenated list parsed in the order: system-wide → user-specific → custom → command-line arguments.
• System configuration resides at /etc/youtube-dl.conf and is skipped when --ignore-config is present.
• User configuration discovery follows XDG standards on Unix, AppData on Windows, and legacy home directory fallbacks, implemented in _readUserConf() at lines 55-89 of youtube_dl/options.py.
• Custom locations specified via --config-location override default lookup paths but still yield precedence to command-line arguments.
• Command-line arguments always win due to the concatenation order defined at lines 33-34 of youtube_dl/options.py.

Frequently Asked Questions

Where does youtube-dl look for user configuration files?

youtube-dl searches multiple locations in sequence according to the _readUserConf() function in youtube_dl/options.py. On Unix systems, it checks $XDG_CONFIG_HOME/youtube-dl/config (or .config/youtube-dl/config as fallback), then legacy paths like ~/youtube-dl.conf. On Windows, it looks in %APPDATA%\youtube-dl\config before falling back to the home directory.

How do I prevent youtube-dl from reading any configuration files?

Use the --ignore-config flag either on the command line or inside the system configuration file itself. When detected by the parser in youtube_dl/options.py (lines 26-28), this flag causes youtube-dl to skip loading both /etc/youtube-dl.conf and any user-specific configuration files, relying solely on command-line arguments and built-in defaults.

Can I specify a custom configuration file location?

Yes, use the --config-location PATH argument to direct youtube-dl to a specific file or directory. If you provide a directory path, youtube-dl looks for youtube-dl.conf inside that directory. This custom source is processed after system and user configs but before command-line arguments, as implemented in the concatenation logic at lines 33-34 of youtube_dl/options.py.

What happens if the same option is defined in multiple configuration files?

Due to the concatenation order system_conf + user_conf + custom_conf + command_line_conf used by the OptionParser in youtube_dl/options.py, later definitions overwrite earlier ones. This means command-line arguments override custom configs, which override user configs, which override system-wide settings. The final effective value comes from the highest-precedence source that defined that specific option.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}