Skip to content

Start typing. Errors match on their exact yt-dlp output.

↑ ↓ to move, ↵ to open esc to close

The yt-dlp Config File: Stop Retyping the Same Flags

Tested on yt-dlp 2026.07.28 Updated

Quick answer

Every flag you have typed twice belongs in yt-dlp.conf. One flag per line, no yt-dlp prefix, no quotes. Create it here:

macOS and Linux 
mkdir -p ~/.config/yt-dlp
nano ~/.config/yt-dlp/config
Windows PowerShell 
New-Item -ItemType Directory -Force "$env:APPDATA\yt-dlp"
notepad "$env:APPDATA\yt-dlp\config.txt"

A config worth starting from

Sensible on almost any machine. Each line is explained below it:

yt-dlp.conf 
# Quality — merged, capped at 1080p, H.264 for compatibility
-S res:1080,vcodec:h264,acodec:m4a
--merge-output-format mp4

# Naming — channel folders, ids kept so nothing collides
-o %(uploader)s/%(title)s [%(id)s].%(ext)s
--restrict-filenames

# Metadata a media library can read
--embed-metadata
--embed-thumbnail
--embed-chapters

# Only the video I linked to, not the playlist it sits in
--no-playlist

# Pacing, so a long job finishes instead of hitting a 429
--sleep-requests 1.5
--retries 10

# Do not stop a playlist because one video is gone
-i

--no-playlist is the line most worth having. Without it, clicking a video that happens to sit inside a 400-video playlist and pasting the URL downloads all 400.

Where the file goes

PlatformPath
Windows%APPDATA%\yt-dlp\config.txt
Windows (alternative)%USERPROFILE%\yt-dlp.conf
macOS, Linux~/.config/yt-dlp/config
macOS, Linux (alternative)~/yt-dlp.conf
System-wide (Unix)/etc/yt-dlp.conf
Per projectyt-dlp.conf in the current directory

Syntax

  • One flag per line. A flag and its value can share a line.
  • No quotes. The file is not parsed by a shell, so quotes end up inside the value.
  • No yt-dlp prefix — the file holds arguments, not commands.
  • # begins a comment.
  • Blank lines are ignored.

The quoting rule is the one that catches people, because it is the opposite of what the command line requires:

wrong — the quotes become part of the filename 
-o "%(title)s.%(ext)s"
right 
-o %(title)s.%(ext)s

Load order, and what wins

yt-dlp reads several files, and later ones override earlier ones. The command line always wins:

  1. System-wide /etc/yt-dlp.conf
  2. User config in ~/.config/yt-dlp/ or %APPDATA%\yt-dlp\
  3. Home directory yt-dlp.conf
  4. A yt-dlp.conf in the current directory
  5. Anything passed with --config-location
  6. The command line

To see exactly what was loaded:

bash 
yt-dlp -v --simulate "URL" 2>&1 | head -20

The header includes a Loaded N config files line naming each one. When a command behaves differently on your machine than in a guide, this is the first thing to check.

Turning something off

Most flags have a negation that works from the command line:

bash 
yt-dlp --no-embed-metadata --yes-playlist "URL"
yt-dlp --ignore-config "URL"

--ignore-config disables every config file for one run. It is the fastest way to answer "is my config doing this", and worth trying before debugging anything else that behaves unexpectedly.

Several configs for several jobs

Keep separate files and select one per run:

~/.config/yt-dlp/music.conf 
-x
--audio-format m4a
--audio-quality 0
--embed-thumbnail
--embed-metadata
--parse-metadata %(title)s:%(artist)s - %(title)s
-o %(artist,uploader)s/%(album,playlist)s/%(track,title)s.%(ext)s
-P ~/Music/yt-dlp
bash 
yt-dlp --config-location ~/.config/yt-dlp/music.conf "URL"

A per-directory yt-dlp.conf is the other useful shape: an archive folder whose config sets its own naming and archive file, so running yt-dlp from inside it does the right thing with no flags at all.

Lines worth thinking twice about

A config file applies to everything, forever, silently. Three that cause trouble later:

  • -f best — caps every download at 360p, and you will not remember writing it.
  • --no-check-certificate — disables TLS verification for every site, permanently. If you needed it once, pass it once.
  • --cookies-from-browser chrome — makes every command depend on Chrome being closed, including the ones that need no cookies at all.

A useful habit: keep the config small and comment why each line is there. Six months later that comment is the difference between "this is deliberate" and "why is everything 360p".

Frequently asked

Why does my config file seem to be ignored?
Usually the wrong location or a Windows extension problem — a file saved as config.txt.txt by Notepad is invisible to yt-dlp. Run yt-dlp -v; the verbose header names every config file it loaded.
Do values need quotes?
No, and adding them breaks things. The config file is not parsed by a shell, so quotes become part of the value. Write -o %(title)s.%(ext)s, not -o "%(title)s.%(ext)s".
How do I turn off something the config sets?
Most flags have a --no- counterpart that overrides on the command line — --no-embed-metadata against --embed-metadata. --ignore-config disables every config file at once, which is the fastest way to prove one is the cause.
Can I have different configs for different jobs?
Yes. Keep them anywhere and select with --config-location. A music config and an archive config living side by side is a common and sensible setup.

Related