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.txtQuote 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.mp4The 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.confin the same folder as the yt-dlp executable. Handy for a yt-dlp.exe you carry on a USB stick. - Home config:
yt-dlp.confin 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_HOMEif set),%APPDATA%\yt-dlp\config.txt(Windows),~/.yt-dlp/configand~/yt-dlp.conf. - System config:
/etc/yt-dlp.confor/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 argumentsIf 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.