yt-dlp

yt-dlp is a feature-rich command-line downloader for video and audio from YouTube and a large list of other sites (a maintained fork of youtube-dl). It needs ffmpeg to merge separate video and audio streams, convert audio and embed metadata. Only download content you have the right to.

Documentation: yt-dlp README, supported sites

Install and Update #

Sites change often. If a download breaks, update first. The apt package is usually old; prefer pipx or the release binary.

Basic Downloads #

Formats #

-S (format sort) is usually easier than writing -f filters. Quote filters so the shell does not treat [, < or & specially.

Audio Extraction #

Playlists and Channels #

Output Templates #

Templates use Python-style fields: %(FIELD)s, with formatting such as %(playlist_index)03d. Show every available field for a video with yt-dlp -j <URL>.

Useful patterns:

yt-dlp -o "%(uploader)s/%(upload_date>%Y-%m-%d)s - %(title)s [%(id)s].%(ext)s" <URL>
yt-dlp --restrict-filenames -o "%(title)s.%(ext)s" <URL>     # ASCII-only, no spaces
yt-dlp --windows-filenames <URL>                              # Safe on Windows and SMB shares

Use -o with -P (paths): -P ~/Videos -P "temp:~/tmp" puts in-progress files in a temp folder.

Cookies and Login #

Needed for age-restricted, members-only or private videos, and to avoid bot checks on some networks.

Treat cookie files as secrets: they grant access to your account. Keep them out of git and chmod 600 them.

Archive File #

The download archive records the IDs of everything already fetched, so re-running a command only grabs new items.

yt-dlp --download-archive archive.txt <PLAYLIST_OR_CHANNEL_URL>

Each line is <EXTRACTOR> <ID>. Delete a line to download that video again. Combine with --break-on-existing to stop at the first video already in the archive (fast for “latest uploads” runs).

Config File #

Put one option per line in a config file. Lines starting with # are comments.

Example:

# ~/.config/yt-dlp/config
-P ~/Videos/yt
-o "%(uploader)s/%(upload_date>%Y-%m-%d)s - %(title)s [%(id)s].%(ext)s"
-S "res:1080,vcodec:h264,acodec:m4a"
--merge-output-format mkv
--embed-metadata
--embed-thumbnail
--download-archive ~/Videos/yt/archive.txt
--no-mtime

Ignore config files for one run with --ignore-config. Check which options are active with yt-dlp -v (the first lines show loaded configs).

Scheduled Downloads #

# crontab -e: check a channel nightly, archive prevents duplicates
30 2 * * * /usr/local/bin/yt-dlp --download-archive /data/archive.txt -P /data/videos "<CHANNEL_URL>" >> /var/log/yt-dlp.log 2>&1

Docker users can run the same job in a container; see Docker.

Troubleshooting #

Not Verified #

Commands were written from the project README and not executed. Site behaviour and bot detection change frequently.