Install yt-dlp for Saving Online Video

yt-dlp is a actively maintained fork of youtube-dl that supports thousands of sites—YouTube, Vimeo, Twitch VODs, and many more. Installing it via pipx gives you an isolated, upgradeable binary without polluting your system Python. This guide covers installation, picking the right format, grabbing subtitles, and automating downloads with a cron job.

Install pipx and yt-dlp

pipx installs Python CLI tools into their own virtual environments but makes them available on your PATH like any normal binary. It is the cleanest way to manage yt-dlp on a desktop system.

Install pipx

Debian / Ubuntu:

sudo apt update && sudo apt install pipx
pipx ensurepath

Fedora / RHEL 9+ / Rocky 9+:

sudo dnf install pipx
pipx ensurepath

Arch Linux:

sudo pacman -S python-pipx
pipx ensurepath

After running pipx ensurepath, open a new terminal (or run source ~/.bashrc) so the updated PATH takes effect.

Install yt-dlp

pipx install yt-dlp

Verify the install:

yt-dlp --version

Output will resemble 2024.04.09 — the date-based version string yt-dlp uses.

Install optional dependencies

ffmpeg is required for merging separate video and audio streams (which YouTube almost always serves), for post-processing, and for thumbnail embedding. Install it from your package manager — not via pipx.

Debian / Ubuntu:

sudo apt install ffmpeg

Fedora (enable RPM Fusion free repo first):

sudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm
sudo dnf install ffmpeg

Arch:

sudo pacman -S ffmpeg

Download a Video — Basic Usage

The simplest invocation downloads the best available quality and merges the streams:

yt-dlp 'https://www.youtube.com/watch?v=EXAMPLE'

Files land in your current directory. Use -P to choose a destination:

yt-dlp -P ~/Videos 'https://www.youtube.com/watch?v=EXAMPLE'

Format Selection

yt-dlp separates the concept of a format code (what the site offers) from the final output. List everything available for a URL before downloading:

yt-dlp -F 'https://www.youtube.com/watch?v=EXAMPLE'

You will see a table of IDs, extensions, resolutions, codecs, and approximate sizes. Pick a specific video+audio combo with -f:

# Format ID 137 (1080p video) merged with 140 (m4a audio)
yt-dlp -f 137+140 'https://www.youtube.com/watch?v=EXAMPLE'

More practically, use yt-dlp's format selector expressions so you do not have to look up IDs every time:

# Best video up to 1080p + best audio, output as mp4
yt-dlp -f 'bestvideo[height<=1080][ext=mp4]+bestaudio[ext=m4a]' \
  --merge-output-format mp4 \
  'https://www.youtube.com/watch?v=EXAMPLE'

# Best single-file format (no merge needed, good for slower machines)
yt-dlp -f 'best' 'https://www.youtube.com/watch?v=EXAMPLE'

For audio-only — podcast archiving, music, etc.:

yt-dlp -f 'bestaudio' --extract-audio --audio-format mp3 \
  'https://www.youtube.com/watch?v=EXAMPLE'

Downloading Subtitles

List all subtitle languages a video provides (including auto-generated captions):

yt-dlp --list-subs 'https://www.youtube.com/watch?v=EXAMPLE'

Download the video with specific subtitles embedded into an mkv container:

yt-dlp --write-subs --sub-langs 'en,fr' \
  --merge-output-format mkv \
  'https://www.youtube.com/watch?v=EXAMPLE'

To grab auto-generated subtitles (YouTube's speech-to-text captions), add --write-auto-subs:

yt-dlp --write-auto-subs --sub-langs 'en' \
  'https://www.youtube.com/watch?v=EXAMPLE'

If you want subtitles as separate .vtt or .srt files rather than muxed in, drop --merge-output-format mkv and add --convert-subs srt:

yt-dlp --write-subs --convert-subs srt --sub-langs 'en' \
  'https://www.youtube.com/watch?v=EXAMPLE'

Persistent Configuration

Typing long flags every time is tedious. yt-dlp reads a config file from ~/.config/yt-dlp/config on Linux. Create it with your preferred defaults:

mkdir -p ~/.config/yt-dlp
cat > ~/.config/yt-dlp/config << 'EOF'
# Save to ~/Videos by default
-P ~/Videos

# Best video up to 1080p merged as mp4
-f bestvideo[height<=1080][ext=mp4]+bestaudio[ext=m4a]
--merge-output-format mp4

# Embed thumbnail and metadata
--embed-thumbnail
--embed-metadata

# English subtitles if available
--write-subs
--sub-langs en
EOF

With this file in place, a bare yt-dlp URL applies all those flags automatically.

Automating Downloads with Cron

A common use case: you maintain a text file of URLs (a playlist archive, a list of channels) and want yt-dlp to check for new content nightly.

Create a URL batch file

mkdir -p ~/Videos/queue
cat > ~/Videos/queue/urls.txt << 'EOF'
https://www.youtube.com/@SomeChannel/videos
https://www.youtube.com/playlist?list=PLEXAMPLE
EOF

Create a download script

cat > ~/Videos/queue/sync.sh << 'EOF'
#!/usr/bin/env bash
set -euo pipefail

BATCH=~/Videos/queue/urls.txt
OUT=~/Videos/archive
ARCHIVE=~/Videos/queue/downloaded.txt

mkdir -p "$OUT"

/home/$USER/.local/bin/yt-dlp \
  --batch-file "$BATCH" \
  --download-archive "$ARCHIVE" \
  -P "$OUT" \
  -f 'bestvideo[height<=1080][ext=mp4]+bestaudio[ext=m4a]' \
  --merge-output-format mp4 \
  --no-progress >> ~/Videos/queue/yt-dlp.log 2>&1
EOF
chmod +x ~/Videos/queue/sync.sh

The --download-archive flag records every downloaded video ID into downloaded.txt. On subsequent runs yt-dlp skips anything already in that file, making reruns safe and fast.

Schedule with cron

crontab -e

Add a line to run the script at 02:00 every night:

0 2 * * * /home/YOUR_USERNAME/Videos/queue/sync.sh

Replace YOUR_USERNAME with your actual username. Avoid ~ in crontab entries — cron may not expand it correctly depending on the shell it uses.

Keeping yt-dlp Updated

Sites change their internals frequently and yt-dlp releases fixes on a rolling basis. Update regularly:

pipx upgrade yt-dlp

To upgrade all pipx-managed tools at once:

pipx upgrade-all

Verification

Confirm the whole pipeline works end-to-end with a short public-domain video:

yt-dlp --simulate --verbose 'https://www.youtube.com/watch?v=BaW_jenozKc'

--simulate runs all the resolution and format logic without actually downloading anything. Check that ffmpeg is detected in the verbose output — look for a line like [debug] ffmpeg: /usr/bin/ffmpeg. If it is missing, the merge step will silently fail.

Troubleshooting

• "yt-dlp: command not found" — pipx writes binaries to ~/.local/bin. Run pipx ensurepath again and restart your shell.
• HTTP 403 or "Sign in to confirm your age" — Export your browser cookies: yt-dlp --cookies-from-browser firefox URL. yt-dlp supports chrome, chromium, firefox, brave, and others.
• Merge produces only video, no audio — ffmpeg is missing or not on PATH. Install it via your package manager and re-run yt-dlp --verbose to confirm detection.
• Cron job does not run — Check journalctl -u cron (Debian/Ubuntu) or journalctl -u crond (Fedora/Arch). Ensure full absolute paths are used in the script and the script is executable.
• Format not available — The site may throttle or geo-restrict certain qualities. Try -f best as a fallback, or check with yt-dlp -F URL to see what is actually offered.