youtube-dl Documentation

Depending on how you installed youtube-dl, use the corresponding method to update to the latest version:

• Manual installation: Run youtube-dl -U (or sudo youtube-dl -U on Linux).
• pip: Run sudo pip install -U youtube-dl.
• Package managers (apt-get, yum, etc.): Use your system's standard update mechanism (e.g., sudo apt-get update && sudo apt-get upgrade youtube-dl). Note that distribution packages are often outdated.

If your package manager provides an outdated version, you can uninstall it and perform a manual installation:

sudo apt-get remove -y youtube-dl
sudo wget https://yt-dl.org/downloads/latest/youtube-dl -O /usr/local/bin/youtube-dl
sudo chmod a+rx /usr/local/bin/youtube-dl
hash -r

The basic syntax for using youtube-dl is:

youtube-dl [OPTIONS] URL [URL...]

Common Options

• -h, --help: Print help text.
• --version: Print program version.
• -U, --update: Update the program to the latest version (may require sudo).
• -i, --ignore-errors: Continue downloading even if an error occurs (e.g., skipping unavailable videos in a playlist).
• --abort-on-error: Stop downloading if an error occurs.
• --list-extractors: List all supported extractors.
• --extractor-descriptions: Output descriptions of all supported extractors.
• --flat-playlist: List videos in a playlist without extracting them individually.
• --no-color: Disable color codes in the output.

To avoid passing credentials as plain text in the command line or shell history, you can use a .netrc file for automatic authentication. This works for extractors that support authentication.

1. Create a .netrc file in your $HOME directory.
2. Set restrictive permissions (read/write only for your user).
3. Add credentials using the format: machine <extractor> login <login> password <password> (where <extractor> is the lowercase name of the extractor).
4. Pass the --netrc flag to youtube-dl or add it to your configuration file.

Windows Note: You may need to manually set the %HOME% environment variable to %USERPROFILE% for this to work.

To add a new site extractor, create a new Python file in youtube_dl/extractor/. The extractor must inherit from InfoExtractor.

Basic Template:

# coding: utf-8
from __future__ import unicode_literals

from .common import InfoExtractor

class YourExtractorIE(InfoExtractor):
    _VALID_URL = r'https?://(?:www\.)?yourextractor\.com/watch/(?P<id>[0-9]+)'
    _TEST = {
        'url': 'https://yourextractor.com/watch/42',
        'md5': 'TODO: md5 sum of the first 10241 bytes of the video file (use --test)',
        'info_dict': {
            'id': '42',
            'ext': 'mp4',
            'title': 'Video title goes here',
            'thumbnail': r're:^https?://.*\.jpg$',
        }
    }

    def _real_extract(self, url):
        video_id = self._match_id(url)
        webpage = self._download_webpage(url, video_id)

Use the --cookies option to provide a path to a cookies file. This is useful for bypassing login requirements or working around CAPTCHAs.

Requirements for the cookies file:

• Must be in Mozilla/Netscape format.
• The first line must be either # HTTP Cookie File or # Netscape HTTP Cookie File.
• Newline format matters: Use CRLF (\r\n) for Windows and LF (\n) for Unix/Linux/macOS. An incorrect format will result in HTTP Error 400: Bad Request.

To avoid re-downloading videos you have already processed, use the --download-archive feature.

1. Initial run: Run youtube-dl with --download-archive <path_to_file> on the playlist. This creates a file containing the identifiers of all successfully downloaded videos.
2. Subsequent runs: Use the same --download-archive <path_to_file> command. youtube-dl will check the file and skip any video ID already present.

To run the youtube-dl package directly from the source code without building it, use the Python module execution flag.

python -m youtube_dl

You can persist settings by placing command-line options into a configuration file. Options in the config file must follow the same syntax as CLI flags (e.g., -o or --proxy) and must not have whitespace after the dash.

File Locations:

• Linux/macOS (System-wide): /etc/youtube-dl.conf
• Linux/macOS (User-specific): ~/.config/youtube-dl/config
• Windows (User-specific): %APPDATA%\youtube-dl\config.txt or C:\Users\<user name>\youtube-dl.conf

Usage Flags:

• --ignore-config: Disable the configuration file for a single run.
• --config-location PATH: Use a specific custom configuration file for a single run.

# Example ~/.config/youtube-dl/config

# Always extract audio
-x

# Do not copy the mtime
--no-mtime

# Use this proxy
--proxy 127.0.0.1:3128

# Save all videos under Movies directory in your home directory
-o ~/Movies/%(title)s.%(ext)s

When downloading HLS streams, youtube-dl can use either its built-in downloader or ffmpeg. While ffmpeg is the default for general compatibility, you can force a preference using:

• --hls-prefer-native: Uses the built-in downloader.
• --hls-prefer-ffmpeg: Uses ffmpeg.

Note: It is generally recommended to avoid hardcoding these in your configuration unless you have a specific reason, as it may cause other videos to fail. If one downloader works significantly better for a specific site, consider filing an issue or pull request instead.

When reporting bugs or debugging, always run youtube-dl with the -v flag. This provides essential diagnostic information including system config, command-line arguments, Python version, and proxy maps.

Note: Provide the output as plain text, not screenshots.

$ youtube-dl -v <your command line>