yt-dlp Command Line Video Downloader Guide (2026 Edition)

If you have ever needed to save a video from the web as an actual file — not a bookmark, not a screen recording, but a real MP4 you can edit, archive, or feed into a pipeline — this yt-dlp command line video downloader guide 2026 is the one to bookmark. It covers installation on Windows, macOS and Linux, the commands behind 90% of real-world jobs, and responsible use for client media workflows.

yt-dlp is a free, open-source command-line program that downloads audio and video from more than a thousand websites. At last count it held over 200,000 stars on GitHub, making it one of the most-starred Python projects in existence — and the de facto standard tool for anyone who moves video files around professionally. Written for developers, content teams and agencies, it takes you from installation to scripted workflows — without the technical or legal landmines.

What is yt-dlp? Start this command line video downloader guide with the basics

It is the community-maintained successor to youtube-dl: forked from the yt-dlc lineage and merged with youtube-dl’s codebase in late 2020, it took over just as youtube-dl’s development stalled. Where youtube-dl still carried Python 2-era compatibility baggage, yt-dlp requires Python 3.11+ and ships fixes at the pace websites change.

The yt-dlp GitHub repository holds more than 200,000 stars and 17,000 forks, is written in Python, and is released under the Unlicense. When we checked it for this guide, it had received commits the same day — and that cadence is the whole product, because every site redesign can break an extractor overnight.

yt-dlp works through “extractors” — site-specific modules that find the actual media files behind a page’s player. The supported-sites list contains over 1,700 of them, from YouTube (the flagship: clips, stories, mixes, feeds, livestreams) to social platforms, broadcasters and podcast hosts, plus a generic fallback. We have added it to our AI tools directory because in practice it behaves less like a utility and more like infrastructure.

What yt-dlp can do

The feature list reads like a media pipeline in a box. The capabilities that matter most in professional use:

• Format selection and sorting. List every stream with -F, pick with -f, and control preference order with -S — resolution and codec quality are preferred over raw bitrate by default. The default selector merges the best video and best audio streams automatically.
• SponsorBlock integration. Mark or remove sponsor segments via the SponsorBlock API — handy when archiving long-form content.
• Subtitles done properly. Download, embed, or extract subtitles, including subtitles pulled from streaming manifests and even live-chat replays treated as subtitle tracks.
• Chapters and sections. Split a video into files by chapter with --split-chapters, or download only a time range with --download-sections — perfect for clipping a segment out of a two-hour webinar.
• Playlists and channels. Pull entire playlists or channel uploads, filter by date or index, and use --flat-playlist to sweep metadata without downloading a byte.
• Authenticated downloads. --cookies-from-browser pulls session cookies straight from your browser, so content behind a login works without hand-copying tokens.
• Output templates. The default %(title)s [%(id)s].%(ext)s naming is sensible, and custom templates organise thousands of files into uploader/date/playlist directory trees on download.
• Plugins and self-updates. External extractors and post-processors can be loaded as plugins, and yt-dlp -U updates the binary in place — the single most important command in this entire guide.
• Speed. Multi-threaded fragment downloads (-N) parallelise HLS/DASH streams, which is the difference between a 40-minute and a 10-minute pull on segmented video.

How yt-dlp works: installation and the commands that matter

Following the official installation instructions, you have three routes: the standalone binaries from the GitHub releases page (yt-dlp.exe for Windows, yt-dlp_macos for macOS, yt-dlp for Linux/BSD — no Python needed), pip install -U yt-dlp with Python 3.11+, or your system package manager. One companion is close to mandatory: ffmpeg, which handles merging separate video/audio streams, conversion, and subtitle embedding. Without it, half the useful flags silently do less than you expect.

Verify the install:

yt-dlp --version
yt-dlp -U   # update to the latest release; run this before any big job

The basic form is yt-dlp [OPTIONS] URL — always quote the URL, since an unquoted & gets eaten by your shell. These six patterns cover the overwhelming majority of real jobs:

# 1. Download a video at the best available quality
yt-dlp "https://www.youtube.com/watch?v=VIDEO_ID"

# 2. See every available format, then pick one explicitly
yt-dlp -F "https://www.youtube.com/watch?v=VIDEO_ID"
yt-dlp -f "bv*+ba/b" "https://www.youtube.com/watch?v=VIDEO_ID"

# 3. Extract audio only (podcasts, interviews, music you own)
yt-dlp -x --audio-format mp3 "URL"

# 4. Grab subtitles alongside the video
yt-dlp --write-subs --sub-langs "en.*" --embed-subs "URL"

# 5. Download one chapter-length section of a long video
yt-dlp --download-sections "*00:10:00-00:12:30" "URL"

# 6. Pull the first ten items of a playlist, with tidy filenames
yt-dlp --playlist-items 1-10 -o "%(playlist_title)s/%(title)s [%(id)s].%(ext)s" "PLAYLIST_URL"

Two habits separate professionals from dabblers. First, keep a config file (~/.config/yt-dlp/config on Linux/macOS, %APPDATA%yt-dlpconfig.txt on Windows) with one option per line, so every run inherits your format, template and subtitle defaults. Second, dry-run bulk jobs: --skip-download --print "%(title)s" shows exactly what a playlist pull would fetch, without fetching it.

Why yt-dlp is trending in 2026

The structural reason is maintenance velocity. Video sites redesign constantly, and every change can break an extractor — the project’s own supported-sites file warns that listed sites are not guaranteed to work and “the only reliable way to check if a site is supported is to try it.” The downloader with same-day fixes wins, and yt-dlp’s cadence is relentless: nightly and master builds exist because waiting for a monthly release means a month of broken downloads.

There is also history: in October 2020, youtube-dl was briefly removed from GitHub after an RIAA DMCA notice, then restored weeks later when GitHub’s review found the takedown overbroad. The community’s energy consolidated around the maintained fork, and yt-dlp has been the default recommendation ever since.

The demand side is simpler: video is the working material of the modern web. Agencies archive client webinars, repurpose their own content, back up training libraries, and feed transcription pipelines. Browser extensions for this job are fragile and often spyware-adjacent; a scriptable CLI with 1,700 extractors is infrastructure you can audit. Done on content you own, media extraction is a close cousin of the web scraping and data extraction work we do for clients.

From our experience: running yt-dlp in production

We have wired yt-dlp into client content pipelines for years. The tool is superb; the operational lessons are where teams get hurt:

• Pin it or update it — never neither. In CI and scheduled jobs, either pin a release and bump it deliberately, or run yt-dlp -U at the start of every batch. A stale binary failing on a redesigned site is the most common “yt-dlp is broken” report — and the tool is never actually broken.
• Expect extractors to break. Build retries and alerting into automated jobs: an extractor that worked Monday can 403 by Friday, and your pipeline should page someone rather than fill a disk with error logs.
• Respect rate limits. --sleep-requests and --retry-sleep exist for a reason. Hammering a site from one IP gets the IP blocked, and then nothing works — including your browser.
• Cookies expire. Sessions die: use a dedicated browser profile for automation logins and re-export on a schedule, instead of debugging auth failures at 2am.
• Keep ffmpeg current. An old ffmpeg paired with a new yt-dlp produces merge failures with cryptic errors. Update them together.
• Throttle bulk jobs. --limit-rate on large pulls is basic bandwidth courtesy — on shared networks it is the difference between a background job and an incident.
• Filename collisions are real. The default [id] suffix prevents two “Final_v2” uploads from overwriting each other — keep it in any custom template.

Responsible use: the rules for agencies

yt-dlp is dual-use in the most literal sense: the same command downloads your own webinar archive and someone else’s copyrighted film. The software is perfectly legal open-source code — legality depends on what you point it at. For agencies, the policy we recommend is simple and written down:

• Download only what you own or are licensed to use — your uploads, client assets handed to you, Creative Commons or public-domain material, and content with explicit written permission. Keep the licenses on file next to the files.
• Do not rip third-party content for client work. “The client found it on YouTube” is not a license. Agencies have been burned reposting footage they did not own, and the platform’s uploader is rarely the rights holder.
• Respect platform terms. YouTube’s Terms of Service prohibit downloading outside its provided features; treat yt-dlp as tooling for content you have rights to, not a way around access controls.
• Prefer official routes when republishing. If the end goal is embedding or sharing, official embeds and APIs carry none of the risk that downloaded-and-reuploaded files do.

Framed this way, yt-dlp is uncontroversial client-asset tooling: archiving your own webinars, backing up your own channel, clipping licensed stock, feeding your own transcription pipeline. That is the use case this guide is written for.

Getting started in 10 minutes

1. Install the prerequisites: the official binary for your OS (or pip install -U yt-dlp with Python 3.11+), plus ffmpeg.
2. Verify and update. Run yt-dlp --version, then yt-dlp -U to make sure you are on the latest release.
3. Download your own video. yt-dlp "URL" — start with content you own while you learn the flags.
4. Learn format selection. yt-dlp -F "URL" lists streams; -f picks one; -S reorders preferences. Try -x --audio-format mp3 for audio extraction.
5. Set up a config file. Put your format choice, output template and subtitle preferences in ~/.config/yt-dlp/config so every run inherits them.
6. Script a small batch. Loop over a text file of URLs, log output, add --sleep-requests 2 between items. When that loop grows into a scheduled job with alerting and retries, you have crossed into workflow automation — where this kind of tooling earns its keep.

Frequently asked questions

Is yt-dlp legal?

The software itself is legal open-source code released under the Unlicense. Legality depends on what you download: your own content, Creative Commons or public-domain material, and licensed assets are fine; downloading copyrighted material you have no rights to is not. This is general information, not legal advice — when in doubt, get written permission.

Is yt-dlp safe to install?

Yes, when obtained from official sources — the GitHub releases page or PyPI. The project publishes SHA256 checksums and GPG signatures for its release files, so you can verify what you downloaded. Avoid random third-party binaries and “yt-dlp Pro” repacks; the real tool is free.

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

yt-dlp is the actively maintained fork that superseded youtube-dl after the latter’s development slowed. It adds SponsorBlock integration, smarter format sorting, cookies-from-browser, chapter splitting, a plugin system, a self-updater, and over 1,700 maintained extractors — while requiring modern Python (3.11+) instead of carrying legacy compatibility.

Do I need ffmpeg with yt-dlp?

Strongly recommended. Merging separate video and audio streams (the default behaviour for best quality), converting formats, embedding subtitles and thumbnails, and splitting by chapters all require ffmpeg. Without it, yt-dlp still downloads, but half its useful features are unavailable.

How do I keep yt-dlp working when a site changes?

Run yt-dlp -U to update to the latest release — extractor fixes ship constantly, sometimes the same day a site breaks. For automated pipelines, either update at the start of every batch or pin a release and bump it deliberately, with alerting so a broken extractor pages someone instead of failing silently.

yt-dlp earns its 200,000 stars not by being clever, but by being maintained — the least glamorous and most valuable property any infrastructure tool can have.

If your team moves a lot of media — archiving webinars, repurposing content, feeding transcription pipelines — we build this tooling into client workflows every week. Contact us and we will scope it properly.