youtube-dl — Command-Line Video Downloader for Hundreds of Sites

Introduction

youtube-dl is a command-line program that lets you download videos from YouTube and over a thousand other sites. It is written in Python and runs on any platform with a Python interpreter, making it one of the most widely used open-source media tools available.

What youtube-dl Does

• Downloads video and audio from 1000+ websites
• Extracts audio-only streams in formats like MP3, AAC, and Opus
• Supports playlist and channel batch downloads
• Fetches subtitles, thumbnails, and metadata alongside media
• Allows format selection and quality control via format codes

Architecture Overview

youtube-dl is a single Python package that ships as both a library and a CLI. Each supported site has an extractor module that parses page HTML or calls site APIs to locate stream URLs. A central downloader component handles HTTP, RTMP, and HLS streams, while a post-processor pipeline handles merging, remuxing, and embedding metadata via FFmpeg when installed.

Self-Hosting & Configuration

• Install via pip: pip install youtube-dl or download the standalone binary
• Requires Python 2.6+ or 3.2+ on Linux, macOS, or Windows
• Optional FFmpeg dependency for merging separate video and audio streams
• Configure defaults in ~/.config/youtube-dl/config (one option per line)
• Supports proxy, rate-limiting, and cookie-based authentication for gated content

Key Features

• Extensive site support with community-contributed extractors
• Automatic retry and resume for interrupted downloads
• Embed thumbnails and subtitles directly into output files
• Output template system for organizing downloads by metadata
• Can be imported as a Python library for programmatic use

Comparison with Similar Tools

• yt-dlp — Actively maintained fork with faster updates and additional features; preferred for new setups
• gallery-dl — Focused on image galleries and boorus rather than video
• streamlink — Specializes in piping live streams to media players
• aria2 — General-purpose download accelerator without site-specific extraction
• wget — Generic HTTP downloader with no video format negotiation

FAQ

Q: Is youtube-dl still maintained? A: Development has slowed since 2021. The community fork yt-dlp receives more frequent updates, but youtube-dl still works for many sites.

Q: Do I need FFmpeg? A: FFmpeg is optional but recommended. Without it, youtube-dl cannot merge separate video and audio streams or convert formats.

Q: Can I download private or age-restricted videos? A: Yes, by passing cookies from your browser session using the --cookies flag or by supplying credentials with -u and -p.

Q: Is downloading videos legal? A: Legality depends on your jurisdiction and the content's license. Downloading content you have the right to access for personal use is generally acceptable, but redistributing copyrighted material is not.

Sources

• https://github.com/ytdl-org/youtube-dl
• https://youtube-dl.org/