youtube-dl

Download a video or playlist

$ youtube-dl '[https://www.youtube.com/watch?v=oHg5SJYRHA0]'

$ youtube-dl [[-F|--list-formats]] '[https://www.youtube.com/watch?v=Mwa0_nE9H7A]'

$ youtube-dl [[-f|--format]] "[best[height<=480]]" '[https://www.youtube.com/watch?v=oHg5SJYRHA0]'

$ youtube-dl [[-x|--extract-audio]] --audio-format [mp3] '[url]'

$ youtube-dl [[-f|--format]] bestvideo+bestaudio '[url]'

$ youtube-dl [[-f|--format]] [mp4] [[-o|--output]] "[%(playlist_index)s-%(title)s by %(uploader)s on %(upload_date)s in %(playlist)s.%(ext)s]" '[url]'

$ youtube-dl --sub-lang [en] --write-sub '[https://www.youtube.com/watch?v=Mwa0_nE9H7A]'

$ youtube-dl [[-f|--format]] "bestaudio" [[-c|--continue]] [[-w|--no-overwrites]] [[-i|--ignore-errors]] [[-x|--extract-audio]] --audio-format mp3 [[-o|--output]] "%(title)s.%(ext)s" '[url_to_playlist]'

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.

-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.

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.

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.

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.

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.

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.

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.

yt-dlp(1), ffmpeg(1), wget(1), curl(1)