CH01 / Open-source tools

yt-dlp: the complete practical guide

Last updated Editorial team Video Downloader Info10 segments~5 min

Key takeaways

  1. yt-dlp is a free, open-source command-line program that downloads audio and video from thousands of websites; it is released into the public domain under the Unlicense.
  2. It runs locally on Windows, macOS and Linux, so your links are never sent to a third-party converter site.
  3. yt-dlp needs FFmpeg to merge separate audio and video streams, which is how most large sites deliver high-resolution video.
  4. The three options that matter most are -f (which format), -S (how to rank formats) and -o (how to name the file).
  5. yt-dlp does not bypass DRM; use it for your own content, openly licensed content or content you have permission to keep.
A terminal emulator window, the kind of interface yt-dlp runs in
Image: Kitty-terminal-emulator-rendering-image,Vitaly Zdanevich,CC BY-SA 4.0,via Wikimedia Commons.

yt-dlp is the reference open-source tool for saving online video to your own disk. You give it a page URL, it finds the media streams behind the player, downloads the best ones and, with FFmpeg, assembles a single playable file. It is a command-line program, which sounds intimidating, but five or six options cover 95 % of real-world use. This guide walks through them in the order you will actually need them.

Before going further: yt-dlp is a tool, not a licence. Use it for your own uploads, for public-domain or Creative Commons material, or for content you have explicit permission to keep. Our page on whether downloading videos is legal explains the rules country by country.

What is yt-dlp and why do professionals use it?

yt-dlp is a fork of the older youtube-dl project, maintained on GitHub by a community of volunteers and released under the Unlicense, which places the code in the public domain. Its supported-sites list runs to well over a thousand extractors, from large video platforms to broadcasters, museum archives and conference sites.

Archivists, OSINT researchers and data journalists favour it for three reasons:

  • It runs locally. Nothing passes through a third-party server, unlike browser “converter” sites (see the risks of online downloader sites).
  • It is scriptable. The same command works on one video or on a list of ten thousand, with an archive file that skips what you already have.
  • It is transparent. Every option is documented in the README, and the code can be audited.

How do I install yt-dlp safely?

Always get yt-dlp from an official channel listed in the project’s installation wiki:

Platform Recommended method Update command
Windows winget install yt-dlp or the yt-dlp.exe release from GitHub winget upgrade yt-dlp or yt-dlp -U
macOS brew install yt-dlp brew upgrade yt-dlp
Linux pip install -U "yt-dlp[default]" in a virtual environment, or the distribution package pip install -U "yt-dlp[default]"

Then install FFmpeg, which yt-dlp calls to merge and convert streams. On Windows, the builds packaged for winget (for example winget install Gyan.FFmpeg) work; on macOS, brew install ffmpeg; on Linux, your package manager. Check both are reachable:

yt-dlp --version
ffmpeg -version

Sites change their players often, and yt-dlp releases fixes frequently. Most “it suddenly stopped working” problems disappear after an update. Recent releases may also require an external JavaScript runtime for certain sites; the README lists the current requirements, so check it rather than relying on old tutorials.

How do I see which formats are available?

Run -F (capital F) to list every format the site offers without downloading anything:

yt-dlp -F "https://example.org/watch/my-own-talk"

You get a table with a format ID, the extension, the resolution, the codecs and the bitrate. Lines marked video only or audio only are separate streams that need merging. That is normal for adaptive streaming formats such as HLS and MPEG-DASH.

How do I choose the quality with -f and -S?

-f selects formats; -S ranks them. The default already picks the best video plus the best audio, so you only need these when you have a constraint.

# Best video up to 1080p + best audio, fallback to best combined file
yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]" URL

# Same idea with sorting: prefer 1080p, then MP4-compatible codecs
yt-dlp -S "res:1080,ext:mp4:m4a" URL
  • bv* means best video (with or without audio), ba best audio, b best combined file.
  • The / is a fallback: if the first expression has no match, the next one is tried.
  • -S "res:1080" means “prefer the resolution closest to 1080 without exceeding it” in the sort order. ext:mp4:m4a favours an MP4 video with M4A audio, which plays everywhere, including old TVs.

Sorting with -S is usually more robust than strict filters with -f, because it degrades gracefully when the exact format does not exist. If you are unsure which codec to keep, our comparison of AV1, VP9, H.264 and HEVC explains the trade-offs.

How do I name and organise the files?

The -o output template uses fields in %(...)s syntax:

yt-dlp -o "%(uploader)s/%(upload_date)s - %(title)s [%(id)s].%(ext)s" URL

Including the [%(id)s] is a good habit: titles change and collide, IDs do not. Add --restrict-filenames if the files will travel to systems that dislike spaces and accents, and --windows-filenames when you save to a Windows or exFAT drive from Linux.

How do I get subtitles, metadata and thumbnails?

yt-dlp --write-subs --write-auto-subs --sub-langs "en,fr" --embed-subs \
       --embed-metadata --embed-thumbnail URL
  • --write-subs takes the subtitles uploaded by the creator; --write-auto-subs adds machine-generated ones where available.
  • --embed-subs stores them inside the file (MKV and MP4 support this), so they cannot get lost.
  • --embed-metadata writes title, date and description into the container.

Formats such as SRT and WebVTT are detailed in our subtitles guide.

How do I extract audio only?

yt-dlp -x --audio-format best URL

-x extracts audio. --audio-format best keeps the original codec without re-encoding, which preserves quality. Forcing mp3 re-encodes and loses a little quality each time; read Opus vs AAC vs MP3 before choosing.

How do I archive a whole channel or playlist without duplicates?

yt-dlp --download-archive archive.txt \
       -o "%(playlist_index)03d - %(title)s [%(id)s].%(ext)s" \
       --sleep-interval 5 --max-sleep-interval 15 PLAYLIST_URL

--download-archive records every finished video ID in archive.txt; next time, those IDs are skipped. That makes a nightly backup of your own channel cheap and safe to re-run. The sleep options space out requests, which is polite to the server and reduces the risk of being rate-limited.

How do I keep my settings in a config file?

Instead of retyping options, put them in a configuration file, one option per line. yt-dlp reads, among other locations, %APPDATA%\yt-dlp\config.txt on Windows and ~/.config/yt-dlp/config on Linux and macOS:

-o %(uploader)s/%(title)s [%(id)s].%(ext)s
-S res:1080,ext:mp4:m4a
--embed-metadata
--embed-subs
--sub-langs en.*,fr.*

Use --ignore-config to run a one-off command without it.

What are the limits of yt-dlp?

  • DRM-protected streams (Widevine, FairPlay, PlayReady) cannot be downloaded in usable form, and circumventing them is illegal in most countries. Our DRM explainer explains why.
  • Accounts and cookies. --cookies-from-browser lets yt-dlp reuse your logged-in session for content you can access, such as your own private uploads. Never share the exported cookie file: it is equivalent to your password.
  • Site changes. Extractors break when sites change; updating fixes most issues.
  • Terms of service. Some platforms forbid downloading in their terms even when copyright would allow it. Read them for the platform you use.

If you prefer clicking to typing, the graphical front-ends for yt-dlp wrap the same engine in a window.

Open-source tools in this guide

ToolLicence
yt-dlpUnlicense (public domain)
FFmpegLGPL 2.1+ (some builds GPL)

Frequently asked questions

Is yt-dlp safe to use?

The official project is open source and published on GitHub at github.com/yt-dlp/yt-dlp. Download it only from that repository, from PyPI or from your operating system's package manager. Copies offered on random download portals can be repackaged with malware.

Why does yt-dlp download video and audio as two files?

Many sites store high-resolution video and audio as separate streams. yt-dlp downloads both and asks FFmpeg to merge them into one file. If FFmpeg is missing, you get two files or a lower-quality combined format instead.

How do I update yt-dlp?

If you use the standalone binary, run yt-dlp -U. If you installed it with pip, run pip install -U yt-dlp. If you used a package manager such as winget, Homebrew or your Linux distribution, update through that manager so it keeps track of the version.

Is yt-dlp legal?

The software itself is legal and widely used by archivists, researchers and journalists. What can be unlawful is what you download: copyrighted material without permission, or content whose platform terms forbid downloading. See our guide on whether downloading videos is legal.

What is the difference between yt-dlp and youtube-dl?

yt-dlp started as a fork of youtube-dl and adds features such as format sorting with -S, SponsorBlock integration, better playlist handling and much more frequent releases. Most youtube-dl options still work, but the defaults differ.

Sources and open data

  1. yt-dlp README and option reference · yt-dlp project (GitHub)
  2. yt-dlp installation wiki · yt-dlp project
  3. Supported sites list · yt-dlp project
  4. The Unlicense · unlicense.org
  5. FFmpeg legal and licence information · FFmpeg project