youtube-dl
Download videos from YouTube and other sites
TLDR
Download a video or playlist
List all formats that a video or playlist is available in
Download a video or playlist at a specific quality
Download the audio from a video and convert it to an MP3
Download the best quality audio and video and merge them
Download video(s) as MP4 files with custom filenames
Download a particular language's subtitles along with the video
Download a playlist and extract MP3s from it
SYNOPSIS
youtube-dl [OPTIONS] URL [URL...]
This command allows users to download content from a specified URL. Multiple URLs can be provided, or a URL pointing to a playlist, which youtube-dl can process accordingly. Options control various aspects like format, output location, and post-processing.
PARAMETERS
-h, --help
Display a help message and exit.
-v, --version
Print program version and exit.
-f, --format FORMAT
Specify video format code. Use '--list-formats' to see available formats.
-o, --output TEMPLATE
Output filename template. Supports variables like '%(title)s', '%(ext)s'.
-a, --batch-file FILE
File containing URLs to download (one URL per line).
-i, --ignore-errors
Continue on download errors, for example to skip unavailable videos in a playlist.
--playlist-start NUMBER
Playlist video to start at (default is 1).
--playlist-end NUMBER
Playlist video to end at (default is last).
--yes-playlist
Confirm downloading entire playlist if URL points to one.
--no-playlist
Download only the video if the URL points to a playlist.
-x, --extract-audio
Convert video files to audio-only files after downloading.
--audio-format FORMAT
Specify audio format (e.g., mp3, aac, flac). Requires --extract-audio.
--audio-quality QUALITY
Specify audio quality (0=best, 9=worst for VBR, or bitrate like 128K).
--embed-thumbnail
Embed thumbnail in the audio file when extracting audio.
--write-description
Write video description to a .description file.
--write-info-json
Write video metadata to a .info.json file.
--write-thumbnail
Write thumbnail image to disk.
--skip-download
Do not download the video; only extract information or list formats.
--list-formats
List all available formats for a video without downloading.
--proxy URL
Use a specified HTTP/SOCKS proxy.
--rate-limit LIMIT
Limit the download speed to a specific rate (e.g., 50K, 1M).
--no-warnings
Suppress warning messages.
--geo-bypass-country CODE
Bypass geographic restrictions via a VPN to a specific country code.
--download-archive FILE
Record and skip already downloaded videos in the given file.
DESCRIPTION
youtube-dl is a powerful, command-line program to download videos and audio from YouTube and thousands of other video hosting websites. It is cross-platform, running on Linux, macOS, and Windows, making it a versatile tool for media acquisition. Users can download individual videos, entire playlists, or specific clips based on various criteria.
Beyond simple downloading, youtube-dl offers extensive options for format selection, quality control, metadata extraction, and post-processing, such as converting videos to audio-only files (e.g., MP3) or embedding thumbnails. Its flexibility and broad site compatibility have made it a go-to utility for archivists, content creators, and everyday users looking to save online media for offline viewing or listening.
CAVEATS
While youtube-dl is a powerful tool, users should be aware of several considerations:
1. Legal and Copyright Issues: Downloading copyrighted content without permission may violate terms of service or copyright laws in various jurisdictions. Users are responsible for ensuring their usage is legal.
2. External Dependencies: For many advanced features, such as merging formats, converting to audio, or embedding metadata, ffmpeg or ffprobe must be installed and accessible in your system's PATH.
3. Site Changes: Video hosting sites frequently update their structures, which can sometimes temporarily break youtube-dl's ability to download from them until the tool is updated.
4. Maintenance: The original youtube-dl project has seen reduced maintenance in recent years. For more active development and better support for newer sites, consider using its community-maintained fork, yt-dlp.
INSTALLATION
youtube-dl can be installed via Python's package manager pip: pip install youtube-dl
or through system package managers on various Linux distributions (e.g., sudo apt install youtube-dl
on Debian/Ubuntu). Users should ensure they have Python and pip installed.
POST-PROCESSING REQUIREMENTS
For post-processing tasks such as merging separate video/audio streams, converting video to audio, or embedding metadata/thumbnails, youtube-dl relies on external tools, primarily ffmpeg and ffprobe. These tools must be installed and accessible in the system's PATH for these features to work correctly. Without them, you might be limited to downloading streams as they are presented by the source.
OUTPUT TEMPLATING
One of youtube-dl's powerful features is its output filename templating. The -o
or --output
option accepts a string that can include various variables extracted from the video's metadata, such as %(title)s
(video title), %(uploader)s
(channel name), %(upload_date)s
, %(id)s
(video ID), and %(ext)s
(file extension). This allows for highly customized and organized file naming conventions for downloaded content.
HISTORY
youtube-dl was initially released in 2006, making it one of the earliest and most enduring command-line tools for downloading online videos. Its open-source nature and continuous development allowed it to adapt to changes in video platforms and support an ever-growing list of websites.
The project gained significant attention in late 2020 when it faced a DMCA takedown notice from the RIAA, alleging copyright circumvention. This event sparked widespread debate about copyright and open-source software, leading to a massive community backlash and support, eventually resulting in GitHub restoring the repository.
Despite its historical significance and widespread adoption, the original youtube-dl project has experienced slowing development and maintenance in recent years. As a result, a highly active and feature-rich fork named yt-dlp emerged, which is now generally recommended for most users due to its more frequent updates and broader site support.