youtube-dl: Command-Line Video Downloader
/youtube-dl
youtube-dl works from the terminal to pull video files off YouTube.com and other sites, distributed as public-domain software under the Unlicense. It runs on Python 2.6, 2.7, or 3.2+ and ships with dozens of flags covering format selection, playlist ranges, and rate limits. Reach for it if you're comfortable scripting downloads from a terminal; skip it if you want a graphical interface instead of typed options.
What is youtube-dl?
youtube-dl is a Python script you run from the command line to fetch video content from YouTube.com and a small set of other video-hosting sites, invoked as `youtube-dl [OPTIONS] URL [URL...]`. It needs a Python interpreter (2.6, 2.7, or 3.2+) but isn't tied to one operating system; the README lists Unix, Windows, and macOS as supported platforms. There's no graphical window here: every download starts with a URL typed after the command.
Key Capabilities
- โExtractor-based site coverage: `--list-extractors` prints every site youtube-dl currently supports, and `--extractor-descriptions` explains what each extractor does.
- โPlaylist range controls: `--playlist-start`, `--playlist-end`, and `--playlist-items` (for example `--playlist-items 1,2,5,8` or `1-3,7,10-13`) pull a slice of a playlist instead of the whole thing.
- โGeo-restriction bypass through `--geo-bypass`, which fakes the X-Forwarded-For header, plus `--geo-bypass-country CODE` for a specific country code using the two-letter ISO 3166-2 format.
- โRate and retry controls: `-r/--limit-rate` caps bandwidth, `-R/--retries` defaults to 10 or "infinite", and `--fragment-retries` covers DASH, hlsnative, and ISM streams on their own.
- โMetadata filtering before a download starts, using `--match-filter` expressions like `like_count > 100 & dislike_count <? 50 & description`, plus `--date`, `--datebefore`, and `--dateafter` for upload-date ranges.
- โSidecar output files: `-o/--output TEMPLATE` controls filenames, `--write-info-json` and `--write-description` save metadata, and `--write-thumbnail` saves the thumbnail image.
- โExternal downloader hand-off through `--external-downloader`, which can delegate the transfer to aria2c, avconv, axel, curl, ffmpeg, httpie, or wget.
- โResumable downloads by default via `-c/--continue`, tracked with `.part` files unless `--no-part` is set.
Installation Guide
youtube-dl documents several install paths, and the right one depends on platform. On Linux, macOS, and other Unix systems, `sudo curl -L https://yt-dl.org/downloads/latest/youtube-dl -o /usr/local/bin/youtube-dl` followed by `sudo chmod a+rx /usr/local/bin/youtube-dl` puts a runnable file in place; `wget` works the same way if `curl` isn't installed. Windows users grab the `.exe` file and drop it anywhere on PATH except the System32 folder under `%SYSTEMROOT%`. `sudo -H pip install --upgrade youtube-dl` installs or updates it through pip. macOS users can also run `brew install youtube-dl` via Homebrew, or `sudo port install youtube-dl` via MacPorts. Whichever path you pick, a Python interpreter (2.6, 2.7, or 3.2+) is required to run it.
Basic Usage and Options
Every call follows the same shape: `youtube-dl [OPTIONS] URL [URL...]`, so multiple URLs can queue in one invocation. Run `youtube-dl --list-extractors` first if you're unsure a site is supported, or `youtube-dl -s -j URL` to simulate a run and print JSON metadata without downloading anything. From there the flags split into groups: Network Options (`--proxy`, `--socket-timeout`, `-4`/`-6` to force IPv4 or IPv6), Video Selection (`--playlist-items`, `--match-filter`, `--age-limit`, `--download-archive`), Download Options (`-r/--limit-rate`, `-R/--retries`, `--external-downloader`), and Filesystem Options (`-o/--output TEMPLATE` for filenames, `--cookies FILE` for authenticated sites, `--cache-dir` for cached player files). `-i/--ignore-errors` is worth knowing early. Without it, one broken video in a playlist stops the whole batch.
Strengths
- โPublic-domain licensing under the Unlicense, with no attribution or copyleft requirement.
- โA large, documented flag set covering network, geo-restriction, filtering, filesystem, thumbnail, and verbosity behavior, all visible in `--help`.
- โSeveral install paths (curl/wget script, pip, Homebrew, MacPorts, Windows .exe), so it fits into different platform setups.
- โResumes partial downloads by default and can hand transfers off to an external downloader like aria2c or ffmpeg.
- โCross-platform per the README, which names Linux/Unix, Windows, and macOS without singling out one as primary.
Current Limitations
- โณThe facts available here don't include a version number, changelog, or note on how quickly extractor code gets updated when a video site changes its page structure, so judging maintenance pace isn't possible from this source alone.
- โณIt's a command-line tool with no graphical interface; `-h/--help` is the built-in guidance, and there's no point-and-click option for anyone who isn't comfortable in a terminal.
- โณRunning it requires a working Python interpreter (2.6, 2.7, or 3.2+) installed separately, even when using the curl or wget install path.
- โณ`--include-ads` is explicitly marked experimental in the documented options, so ad-related downloading isn't a fully supported behavior.
- โณDay-to-day install requires either `sudo` on Unix systems or placing a file on PATH on Windows by hand; neither path is a one-click installer.
Exploring Alternatives
Common Questions
youtube-dl isn't tied to one operating system: per the README it runs on Unix-type systems, Windows, and macOS, as long as a compatible Python interpreter is installed.
youtube-dl sits in the public domain, listed on GitHub as licensed under the Unlicense, so there's no attribution or copyleft requirement for reuse.
Running `youtube-dl -U` (or `--update`) updates youtube-dl to the latest version; the README notes you may need `sudo` if it's installed in a system directory. Installing via `sudo -H pip install --upgrade youtube-dl` updates it too.
youtube-dl downloads from more than just YouTube.com: the README describes it as covering YouTube.com and other video sites, and `--list-extractors` prints every site it currently supports.
youtube-dl handles playlists directly through the URL, with `--playlist-start`, `--playlist-end`, and `--playlist-items` to grab a specific range, plus `--yes-playlist` to force playlist mode when a URL matches both a video and a playlist.
youtube-dl includes `--geo-bypass`, which fakes the X-Forwarded-For header to work around geographic restrictions, along with `--geo-bypass-country CODE` for a specific two-letter country code.
The problem it solves
Video sites don't expose a stable download button, and the pages that stream video embed their URLs inside JavaScript players that change often. youtube-dl's own `--list-extractors` output is a running answer to that churn: a maintained list of per-site extraction logic instead of one generic scraper trying to handle every video site the same way.
Best use cases
- โขArchiving a channel's back catalog with `--download-archive FILE`, which skips videos already recorded from a previous run.
- โขPulling a video's metadata and thumbnail without the video file itself, using `--skip-download` alongside `--write-thumbnail` or `--write-info-json`.
- โขScripting a batch job against a list of URLs with `-a/--batch-file`, one URL per line, instead of calling the command once per video.
- โขGrabbing a specific slice of a long playlist with `--playlist-items`, rather than pulling every video just to reach the five you want.
- โขChecking what a URL would produce before committing to a download, using `-s/--simulate` with `-g/--get-url` or `-j/--dump-json`.
Who should try it โ and who should skip
Try youtube-dl if you're comfortable typing commands and want direct control over format, playlist range, rate limiting, or filesystem output through explicit flags instead of a settings menu. Skip it if you want a point-and-click app: everything here runs from a terminal, with `-h/--help` as the built-in guidance, or if you can't install a Python interpreter, since the README lists 2.6, 2.7, or 3.2+ as requirements.
Curious whether youtube-dl is right for you?
Let ChatGPT, Claude, or Perplexity look into it โ click below and see what AI actually says about youtube-dl.