yt-dlp Cheat Sheet: Download Video, Audio, and Subtitles From the Command Line

yt-dlp is the free, open-source command-line YouTube downloader I reach for whenever I need video, audio, or subtitles off the command line. It is the maintained community fork of youtube-dl, costs nothing, ships no ads or watermarks, and runs entirely on your own machine. This page is the reference I keep open: every flag worth knowing, grouped by what you are actually trying to do. Build a command first, then scroll for the detail.

yt-dlp --merge-output-format mp4 "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Goal: download the video from this YouTube link.

Run this command in my shell:

    yt-dlp --merge-output-format mp4 "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

First check whether `yt-dlp` is installed (run `command -v yt-dlp`). If it is not, install it with my system's package manager before running anything: macOS `brew install yt-dlp ffmpeg`, Debian/Ubuntu `sudo apt install yt-dlp ffmpeg`, Fedora `sudo dnf install yt-dlp ffmpeg`, Windows `winget install yt-dlp ffmpeg`. Then run the command above.

Show me any command that needs sudo before you run it, tell me where the output file landed when you are done, and do not run anything else.

yt-dlp is a community fork of youtube-dl. Many familiar options carry over, but defaults and compatibility differ; consult the migration notes when adapting an older command.

Download only what you have the right to. Saving your own uploads, Creative Commons material, or content the rights holder permits is one thing; redistributing copyrighted video, or bulk-downloading in a way that violates YouTube's (or any site's) Terms of Service, is another. This reference is for the legitimate cases. What you do with the file is on you.

A note that runs through the whole sheet: install ffmpeg. yt-dlp needs it to merge the separate video and audio streams modern YouTube serves, and to extract or convert audio. The single most common "it only gave me 720p" or "audio extraction failed" complaint is a missing ffmpeg.

The cheat sheet

Everything below is grouped the way I think about a download: get it installed, grab something, then refine quality, audio, subtitles, scale to playlists, and clean up the output.

Install and keep it current

Pick the line for your platform from the install block above. The non-negotiable extra is ffmpeg: Homebrew (brew install yt-dlp ffmpeg) bundles it in one command; on Linux install it with apt/dnf/pacman; on Windows run winget install Gyan.FFmpeg alongside yt-dlp.

Keeping yt-dlp current is not optional with this tool. YouTube changes its player often enough that a stale build simply stops working, and updating is the first thing to try when a download breaks. The standalone binary self-updates with yt-dlp -U; a pipx install updates with pipx upgrade yt-dlp; Homebrew uses brew upgrade yt-dlp. Distro packages (the apt one in particular) lag badly, which is why I prefer pipx for a cross-platform install.

Check dependencies before copying a download command

Run these checks separately:

yt-dlp --version
ffmpeg -version
deno --version

For full YouTube support, current yt-dlp also needs its JavaScript challenge-solving components and a supported external JavaScript runtime. Deno is the recommended runtime in the official EJS setup guide. Packaging differs: the default Python extras install yt-dlp-ejs, while other distributions may bundle it differently. Follow that guide for your install method.

First inspect formats with yt-dlp -F "URL", then choose one download command. Do not paste the whole cheat sheet as a script: the entries are alternatives. Rate limits, unavailable media, and account restrictions can still prevent a download.

Picking the quality

Run yt-dlp -F "URL" to see what a video actually offers: a table of format IDs, resolutions, codecs, and sizes. Then select with -f. The selector I use almost always is bv*[height<=1080]+ba/b[height<=1080], which reads as "best video at or below 1080p, plus best audio, or fall back to the best single file." Change 1080 to whatever ceiling you want; the [height<=N] filter is a ceiling, not a request, so you only get 4K if the creator uploaded 4K.

The trap to avoid is -f best. On modern YouTube the high resolutions are served as separate video-only and audio-only streams, and best only matches a single already-combined (muxed) file, which YouTube caps at around 720p. So -f best quietly hands you 720p and people conclude yt-dlp "can't do 1080p." The bv*+ba selector plus ffmpeg is the fix. For the full walkthrough, including Shorts and the bot check, see how to download a YouTube video in any quality.

Audio only

For an MP3 file, install ffmpeg and run:

yt-dlp -x --audio-format mp3 --audio-quality 0 "URL"

This converts the selected audio to MP3. A higher output bitrate does not restore detail missing from the source. For an available native M4A track without an Opus-to-AAC conversion, select that format explicitly:

yt-dlp -f "ba[ext=m4a]" -x --audio-format m4a "URL"

That command fails if no matching M4A source is available, rather than silently transcoding a different codec. Use yt-dlp -F "URL" to inspect formats first. Add --embed-thumbnail --embed-metadata if you want supported artwork and tags. See MP3, M4A, and Opus audio downloads for more options.

Subtitles and transcripts

yt-dlp --list-subs "URL" shows which languages a video has, including auto-generated captions. To pull the text without the video, combine --skip-download with --write-subs --write-auto-subs --sub-langs en --convert-subs srt. That writes an SRT file (or VTT if you skip the conversion) and nothing else, which is exactly what you want when feeding a summarizer or taking notes. For converting captions to clean plain text, see extract a YouTube video's transcript or captions.

Playlists, channels, and archives

Point yt-dlp at a playlist URL or a channel @handle URL and it downloads the lot. Two flags make bulk jobs sane. --download-archive archive.txt records every video ID it finishes, so re-running the same command skips what you already have, which turns a one-shot grab into something you can run weekly. --playlist-items 1-10 (or a comma list) limits the range. An output template like -o "%(playlist_index)s - %(title)s.%(ext)s" numbers the files so they sort in playlist order. The full resumable channel workflow, with rate limiting, is in download a YouTube playlist or channel.

Cookies, auth, and the Chrome gotcha

When YouTube interrupts a download with "Sign in to confirm you're not a bot," or when a video is members-only, age-restricted, or region-locked and you have legitimate access, hand yt-dlp your browser cookies:

yt-dlp --cookies-from-browser firefox "URL"

Cookie support depends on the browser, OS, profile permissions, and encryption. Chromium app-bound encryption on Windows can prevent extraction; this is not a universal ban on Chrome across every platform. Consult the yt-dlp cookie FAQ. Cookies are account credentials: keep exports private and never include them in shared logs.

Being polite to the server

For anything beyond a single video, throttle yourself. --sleep-requests 1 puts a second between requests; -r 3M (or its long form --limit-rate 3M) caps the download rate. This is partly courtesy and partly self-preservation: hammering a site is the fastest way to trip its bot detection and get your IP rate-limited. The same etiquette applies to every extractor, including TikTok video downloads and Facebook video downloads.

Output templates

By default yt-dlp bakes the video ID into the filename. An output template (-o) fixes that. -o "%(title)s.%(ext)s" gives a readable name; -o "%(uploader)s/%(upload_date)s - %(title)s.%(ext)s" builds a per-uploader folder tree dated by upload. There are dozens of fields (uploader, resolution, id, playlist_index); the percent-paren-s syntax is the standard output-template form documented in the yt-dlp README.

Post-processing

The post-processors run after the download finishes. --embed-subs (with --write-subs) and --embed-chapters fold subtitles and chapter markers into the file. --remux-video mp4 repackages into MP4 without re-encoding when the codecs are already compatible, which is fast and lossless. --sponsorblock-mark all uses the community SponsorBlock database to mark sponsor, intro, and outro segments as chapters; swap mark for remove to physically cut them out. These compose with everything above, so a single command can download at 1080p, embed subtitles, and strip sponsor segments in one pass.

FAQ

See also

• How to download a YouTube video (any quality): the full walkthrough with resolution selection, Shorts, and the bot check.
• Download YouTube audio: extract audio directly to M4A, Opus, or MP3 with -x --audio-format.
• Download a YouTube playlist or channel: the bulk workflow with --download-archive and output templates.
• Extract a YouTube video's transcript or captions: pull the subtitles as plain text, no video.
• Download a TikTok video: the same tool, with TikTok's cookie note.
• Download a TikTok profile: grab every video from one account with an archive file.
• Download an Instagram Reel: pull a Reel (and what Instagram needs for cookies).
• Download a Facebook video: save a public Facebook video from the command line.