yt-dlp - Command-Line Audio and Video Downloader

yt-dlp is the command-line downloader that actually works. It is released into the public domain under the Unlicense, requires Python 3.10 or newer, and has shipped 641 releases.

Almost everyone installs it wrong, and the project says so in its own README.

yt-dlp publishes three release channels — stable, nightly and master — and its documentation is unusually blunt about what stable means:

“the latest stable release is often ‘stale’ and prone to external breakage (i.e. sites changing things on their end and breaking yt-dlp).”

And about the alternative:

“The nightly channel offers releases that publish shortly before midnight UTC on any day that sees changes to the codebase. This channel serves as a snapshot of the project’s development, and it is the recommended channel for regular users of yt-dlp.”

That emphasis is the project’s own, not ours.

We then checked what the two channels currently contain. The latest stable release on the package index is 2026.8.19 — 19 August. The development releases since then are dated 27 August, 29 August, 30 August, 16 September, 27 September and 10 October.

So a plain pip install yt-dlp today installs a build from nearly two months ago, on the channel its maintainers describe as stale. Every extractor fix made since August is in a channel you did not opt into.

Installing the channel you actually want

The nightly releases are published to PyPI as pre-releases, which means pip needs to be told to accept them:

pip install --pre -U yt-dlp

For a standalone binary, switch channel in place:

yt-dlp --update-to nightly

--update-to CHANNEL switches channels, and --update-to CHANNEL@TAG pins or rolls back to a specific release within one — useful when a nightly introduces a regression and you need yesterday’s build.

There is one more line in the README worth internalising before you report a problem:

“Any user experiencing an issue with the stable release should install or update to the nightly release before submitting a bug report”

Most yt-dlp “bugs” are a site change that was already fixed. Updating first is both faster for you and courteous to the maintainers.

Why it is built this way

The architecture explains the release policy, and understanding it makes the tool predictable instead of mysterious.

yt-dlp is a large collection of site-specific extractors wrapped in a common downloader. Each extractor encodes how one site currently structures its pages, its API responses and its media URLs. When a site changes any of that — which happens constantly, sometimes deliberately — the extractor for that site breaks, and only that one.

So yt-dlp’s correctness is not a property of the software; it is a property of how recently the software was updated relative to the site you are pointing it at. That is why a monthly stable cadence cannot work, and why the project pushes nightlies. A downloader a fortnight old is a downloader with a fortnight of unfixed sites in it.

The practical habit that follows: update before you troubleshoot. When something that worked last week stops working, the first action is an update, not an investigation. It resolves the majority of cases in ten seconds.

The Unlicense, and what it actually means

Most projects pick MIT or Apache. yt-dlp uses the Unlicense, which is a public-domain dedication — a release of copyright rather than a grant of permissions.

In practice this is the most permissive thing available: no attribution requirement, no notice to preserve, no conditions at all. You can embed yt-dlp in a commercial product without a licence file. That is genuinely unusual and worth knowing if you are building something on top of it.

What the licence does not do is settle anything about what you download. The licence covers the code; it has no bearing on the copyright of the media, or on the terms of service of the site you fetch it from. Those are separate questions and they are yours.

The defensible uses are the obvious ones: archiving content you created, saving material that is explicitly licensed for reuse, downloading your own uploads, keeping a local copy of something you have a right to. Bulk-downloading other people’s catalogues is a different activity, and no amount of permissive licensing on the tool changes that.

Practical notes

Install ffmpeg. yt-dlp fetches streams; ffmpeg merges and converts them. Without it, you are limited to whatever single pre-muxed format a site happens to offer, and the quality options silently shrink. This is the most common cause of “why is my download low quality.”

Format selection is the skill. The -f syntax for choosing between video and audio streams by codec, resolution and bitrate is where the tool’s real power sits, and it is worth twenty minutes with the documentation rather than copying a command from a forum.

Rate-limit yourself. The tool will happily saturate your connection and hammer a server. Being conservative keeps your IP usable.

A standard utility, kept current

yt-dlp is a standard utility — for archivists, for anyone building a personal media library, for pulling down a conference talk to watch on a train. It is in the same category of useful as a good HTTP client: not exciting, consistently correct, and worth keeping current. For a wider sweep of command-line tooling in this vein, the dev-tools archive collects the rest — and Scrapling faces the same structural problem from the other direction, adapting when a page changes under it.

The finding: yt-dlp’s own README calls its default stable channel stale and recommends nightly for regular users — and the gap is real, with stable sitting at 2026.8.19 while nightlies shipped as recently as 10 October. Install with pip install --pre -U yt-dlp or switch with yt-dlp --update-to nightly, and update before you debug.