# Understanding the youtube-dl Configuration File System and Precedence Rules

> Master youtube-dl configuration files. Learn how command-line arguments, custom configs, user, and system settings interact with clear precedence rules for efficient downloads.

- Repository: [youtube-dl/youtube-dl](https://github.com/ytdl-org/youtube-dl)
- Tags: deep-dive
- Published: 2026-02-25

---

**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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/options.py), the parser combines sources in this order:

```python
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`](https://github.com/ytdl-org/youtube-dl/blob/main//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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main//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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/options.py). This example demonstrates how different sources combine and override each other:

```python
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`](https://github.com/ytdl-org/youtube-dl/blob/main//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`](https://github.com/ytdl-org/youtube-dl/blob/main//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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/options.py) (lines 26-28), this flag causes youtube-dl to skip loading both [`/etc/youtube-dl.conf`](https://github.com/ytdl-org/youtube-dl/blob/main//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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/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.