About this project

youtube-dl is a command-line program to download videos from YouTube.com and many other video platforms. It is written in Python, works cross-platform (Linux, macOS, Windows), and requires Python 2.6/2.7 or 3.2+. ## Installation Available via multiple methods: - Direct binary download: `sudo curl -L https://yt-dl.org/downloads/latest/youtube-dl -o /usr/local/bin/youtube-dl` - pip: `sudo -H pip install --upgrade youtube-dl` - macOS Homebrew: `brew install youtube-dl` - macOS MacPorts: `sudo port install youtube-dl` - Windows: Download the .exe and place it on PATH (not in System32). ## Core Features - Downloads videos and subtitles from 1000+ supported sites using dedicated extractors. - Full playlist support with range selection (`--playlist-start`, `--playlist-end`, `--playlist-items`), reverse order, and random order. - Video format selection and filtering by resolution, container, codec, filesize, duration, view count, and date. - Geo-restriction bypass via fake X-Forwarded-For headers, custom country codes, or IP block exceptions. - Network options: HTTP/HTTPS/SOCKS proxies, IPv4/IPv6 forcing, socket timeouts, custom user agents and referers. - External downloader support (aria2c, curl, ffmpeg, wget, axel, etc.) for advanced downloading scenarios. - Resume partially downloaded files; retry configurable retries for both full fragments and individual fragments. - Output filename templating with extensive metadata keys (title, uploader, upload date, resolution, format, etc.). - Optional output artifacts: thumbnails (single or all formats), `.info.json` metadata, `.description` files, `.annotations.xml`. ## Common Usage Patterns Basic download: `youtube-dl <URL>` Download playlist items 5 through 10: `youtube-dl --playlist-items 5-10 <playlist_URL>` Select best video only: `youtube-dl -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]" <URL>` Set output template: `youtube-dl -o "%(title)s [%(id)s].%(ext)s" <URL>` Download subtitles: add `--write-subs --sub-langs en` to the command. Dry-run without downloading: `youtube-dl --skip-download <URL>` Dump JSON metadata: `youtube-dl --dump-json <URL>` Rate limit: `youtube-dl --limit-rate 50K <URL>` ## Configuration Options can be placed in config files: - Global: `/etc/youtube-dl.conf` - User: `~/.config/youtube-dl/config` (Linux/macOS) or `%APPDATA%/youtube-dl/config.txt` (Windows) Use `--config-location` to specify a custom path, or `--ignore-config` to skip reading any config file. ## Embedding youtube-dl can be used as a Python library, embedding extraction and download logic into scripts and applications. ## Licensing Released to the public domain — free to modify, redistribute, and use in any manner.