ytdlp.org

Practical yt-dlp docs: install, commands, fixes, cookies, and workflows.

Current section

Reference

The yt-dlp config file: location, syntax and which one wins

If you type the same flags every time (an output folder, a format, cookies), put them in a config file and yt-dlp applies them to every run. It's a plain text file of command-line options. The only tricky parts are where it goes, and that yt-dlp can pick up more than one.

Quick answer

# Linux / macOS
mkdir -p ~/.config/yt-dlp
nano ~/.config/yt-dlp/config

# Windows (PowerShell)
mkdir "$env:APPDATA\yt-dlp"
notepad "$env:APPDATA\yt-dlp\config.txt"

Put one option per line, exactly as you'd type it after yt-dlp. Then run any command with -v to confirm it loaded.

A starter config

# ~/.config/yt-dlp/config
# Lines starting with # are comments

# save to ~/Videos as "Uploader - Title.ext"
-o "~/Videos/%(uploader)s - %(title)s.%(ext)s"

# best video up to 1080p plus best audio, else the best single file
-f "bv*[height<=1080]+ba/b"

# ASCII-only, no spaces in values taken from the video
--restrict-filenames

# skip anything already downloaded
--download-archive ~/Videos/archive.txt

Quote any value with spaces, like the output template, the same way you would in a shell. With this file in place, we ran yt-dlp -v --print filename on a sample MP4 (yt-dlp 2026.10.26, November 2026) and yt-dlp reported:

[debug] User config "/home/you/.config/yt-dlp/config": ['-o', '~/Videos/%(uploader)s - %(title)s.%(ext)s', '--restrict-filenames', '-f', 'bv*[height<=1080]+ba/b', ...]
/home/you/Videos/NA - sample-5s.mp4

The NA is the uploader field: that file has none. Note that --restrict-filenames only cleans the values that come from the video; the literal - you wrote in the template keeps its spaces. Output templates have their own guide: yt-dlp output templates.

Where yt-dlp looks

yt-dlp checks these places on every run. The labels are what -v prints:

  • Portable config: yt-dlp.conf in the same folder as the yt-dlp executable. Handy for a yt-dlp.exe you carry on a USB stick.
  • Home config: yt-dlp.conf in the folder you run yt-dlp from (unless you set -P home:). See the gotcha below.
  • User config: the first one that exists of ~/.config/yt-dlp/config (Linux, macOS; $XDG_CONFIG_HOME if set), %APPDATA%\yt-dlp\config.txt (Windows), ~/.yt-dlp/config and ~/yt-dlp.conf.
  • System config: /etc/yt-dlp.conf or /etc/yt-dlp/config, for every user on the machine.

yt-dlp loads all of them, and when two set the same option, the command line beats the portable config, which beats home, then user, then system. We checked the order: with a yt-dlp.conf containing -o "proj-%(title)s.%(ext)s" in the current folder and the user config above, -v listed both, and the file came out as proj-sample-5s.mp4.

Skip it, or use a different one

# ignore every config file for this run
yt-dlp --ignore-config "<URL>"

# use only a specific file (e.g. one per project or per site)
yt-dlp --ignore-config --config-locations ./music.conf "<URL>"

# override one option from the config for this run
yt-dlp -o "%(title)s.%(ext)s" "<URL>"

--config-locations takes a file or a folder and can be repeated. Keeping a music.conf with -x --audio-format mp3 and a video.conf next to it is a clean way to switch setups.

When the config breaks yt-dlp

A bad line in any config file stops every run, even ones that don't use that option:

yt-dlp: error: --print-to-file option requires 2 arguments

If yt-dlp suddenly fails on every URL with an option error you didn't type, run with --ignore-config. If that works, the problem is in a config file, and -v (once the error is fixed) shows you which one.

The gotcha: yt-dlp.conf in the current folder

Because yt-dlp reads yt-dlp.conf from whatever folder you run it in, a file left in a project or downloads folder silently changes your output there and nowhere else. If yt-dlp behaves differently in one folder, run it with -v there and look for a Home config line. The same goes for scripts and cron jobs: run them with --ignore-configand pass every option explicitly, so a config file on the machine can't change what they do.

Automation

Running this on a schedule? See the API version.

Paste a link and watch one API call do what your batch script does — extraction, retries, and site breakage handled.

Building this into an app? See the API your backend calls instead

Frequently asked questions

Where is the yt-dlp config file?

On Linux and macOS, create ~/.config/yt-dlp/config (or $XDG_CONFIG_HOME/yt-dlp/config). On Windows, use %APPDATA%\yt-dlp\config.txt. yt-dlp also reads a yt-dlp.conf next to the yt-dlp executable and one in the folder you run it from. None of these exist until you create them.

How do I check which config file yt-dlp is using?

Run any command with -v. The debug header prints a line per file it loaded, such as [debug] User config "/home/you/.config/yt-dlp/config": [...], with the options it read from it. If no config line appears, no file was found.

Do command-line options override the config file?

Yes. Anything you type on the command line wins over the same option in a config file, so a config can hold your defaults and you override them per run. --ignore-config skips the config files entirely.

What is the syntax of the yt-dlp config file?

The same options you'd type on the command line, usually one per line. Lines starting with # are comments. Quote values that contain spaces, like an output template, exactly as you would in a shell.

Straightforward yt-dlp help for installs, commands, fixes, cookies, and repeatable workflows.

ytdlp.org is an independent, community-maintained documentation site. It is not affiliated with the yt-dlp project — the official source code lives at github.com/yt-dlp/yt-dlp.