MajorWiki/03-opensource/media-creative/yt-dlp.md

yt-dlp — Video Downloading

What It Is

yt-dlp is a feature-rich command-line video downloader, forked from youtube-dl with active maintenance and significantly better performance. It supports YouTube, Twitch, and hundreds of other sites.

---

Installation

Fedora

sudo dnf install yt-dlp
# or latest via pip:
sudo pip install yt-dlp --break-system-packages

Update

sudo pip install -U yt-dlp --break-system-packages
# or if installed as standalone binary:
yt-dlp -U

Keep it current — YouTube pushes extractor changes frequently and old versions break.

---

Basic Usage

# Download a single video (best quality)
yt-dlp https://www.youtube.com/watch?v=VIDEO_ID

# Download to a specific directory with title as filename
yt-dlp -o "/path/to/output/%(title)s.%(ext)s" URL

---

Plex-Optimized Download

Download best quality and auto-convert to HEVC for Apple TV direct play:

yt-dlp URL

That's it — if your config is set up correctly (see Config File section below). The config handles format selection, output path, subtitles, and automatic AV1/VP9 → HEVC conversion.

[!note] bestvideo[ext=mp4] caps at 1080p because YouTube only serves H.264 up to 1080p. Use bestvideo+bestaudio to get true 4K, then let the post-download hook convert AV1/VP9 to HEVC. See Plex 4K Codec Compatibility for the full setup.

---

Playlists and Channels

# Download a full playlist
yt-dlp -o "%(playlist_index)s - %(title)s.%(ext)s" PLAYLIST_URL

# Download only videos not already present
yt-dlp --download-archive archive.txt PLAYLIST_URL

--download-archive maintains a file of completed video IDs — re-running the command skips already-downloaded videos automatically.

---

Format Selection

# List all available formats for a video
yt-dlp --list-formats URL

# Download best video + best audio, merge to mp4
yt-dlp -f 'bestvideo+bestaudio' --merge-output-format mp4 URL

# Download audio only (MP3)
yt-dlp -x --audio-format mp3 URL

---

Config File

Persist your preferred flags so you don't repeat them every command:

mkdir -p ~/.config/yt-dlp
cat > ~/.config/yt-dlp/config << 'EOF'
--remote-components ejs:github
--format bestvideo+bestaudio
--merge-output-format mp4
--output /plex/plex/%(title)s.%(ext)s
--write-auto-subs
--embed-subs
--exec /usr/local/bin/yt-dlp-hevc-convert.sh {}
EOF

After this, a bare yt-dlp URL downloads best quality, saves to /plex/plex/, embeds subtitles, and auto-converts AV1/VP9 to HEVC. See Plex 4K Codec Compatibility for the conversion hook setup.

---

Running Long Downloads in the Background

For large downloads or playlists, run inside screen or tmux so they survive SSH disconnects:

screen -dmS yt-download bash -c \
  "yt-dlp -o '/plex/plex/%(title)s.%(ext)s' PLAYLIST_URL 2>&1 | tee ~/yt-download.log"

# Check progress
screen -r yt-download
# or
tail -f ~/yt-download.log

---

Subtitle Downloads

The config above handles subtitles automatically via --write-auto-subs and --embed-subs. For one-off downloads where you want explicit control over subtitle embedding alongside specific format selection:

yt-dlp -f 'bestvideo[vcodec^=avc]+bestaudio[ext=m4a]/bestvideo+bestaudio' \
    --merge-output-format mp4 \
    -o "/plex/plex/%(title)s.%(ext)s" \
    --write-auto-subs --embed-subs URL

This forces H.264 video + M4A audio when available — useful when you want guaranteed Apple TV / Plex compatibility without running the HEVC conversion hook.

---

Troubleshooting

For YouTube JS challenge errors, missing formats, and n-challenge failures on Fedora — see yt-dlp YouTube JS Challenge Fix.

YouTube player client errors: If downloads fail with extractor errors, YouTube may have broken the default player client. Override it:

yt-dlp --extractor-args "youtube:player-client=default,-tv_simply" URL

This can also be added to your config file as a persistent workaround until yt-dlp pushes a fix upstream. Keep yt-dlp updated — these breakages get patched regularly.

---

Tags

#yt-dlp #youtube #video #plex #linux #media #dev-tools