How to Use yt-dlp: A Complete Guide

By /

How to Use yt-dlp: A Complete Guide

yt-dlp is a powerful command-line program for downloading videos and audio from YouTube and thousands of other sites. It’s a fork of the now-inactive youtube-dl, and offers significant improvements in terms of speed, features, and ongoing maintenance. This guide will walk you through everything you need to know to get started with yt-dlp, from installation to advanced usage.

1. Installation

yt-dlp is available on most operating systems. The easiest way to install is often via a package manager. If a package manager isn’t readily available, the manual install method is reliable.

A. Package Managers (Recommended):

  • Windows (using Chocolatey):

    bash
    choco install yt-dlp ffmpeg
    (You’ll need to install Chocolatey first if you don’t have it.) ffmpeg is a crucial dependency for many yt-dlp features, especially for merging video and audio streams.

  • macOS (using Homebrew):

    bash
    brew install yt-dlp ffmpeg
    (Install Homebrew first if you don’t have it.)

  • Linux (using your distribution’s package manager):
    The package name is usually yt-dlp. Examples:

    • Debian/Ubuntu:
      bash
      sudo apt update
      sudo apt install yt-dlp ffmpeg

    • Fedora/CentOS/RHEL:
      bash
      sudo dnf install yt-dlp ffmpeg
      (You might need to enable the RPM Fusion repository first).

    • Arch Linux:
      bash
      sudo pacman -S yt-dlp ffmpeg

B. Manual Installation (if package managers aren’t available):

  • Windows:

    1. Download the yt-dlp.exe file from the yt-dlp GitHub releases page.
    2. Place yt-dlp.exe in a folder that’s in your system’s PATH environment variable (e.g., C:\Windows\System32 or a dedicated folder you add to PATH). Adding a folder to your PATH allows you to run yt-dlp from any command prompt location.
    3. Download ffmpeg and ffprobe binaries from a reputable source (e.g., ffmpeg.org). Place these in the same folder as yt-dlp.exe or another folder in your PATH.
    4. To add a folder to your PATH:
      • Search for “environment variables” in the Windows search bar.
      • Click “Edit the system environment variables”.
      • Click “Environment Variables…”.
      • Under “System variables”, find the “Path” variable, select it, and click “Edit…”.
      • Click “New” and add the path to the folder containing yt-dlp.exe.
      • Click “OK” on all open windows.

  • macOS/Linux:

    1. Download the yt-dlp file (no extension) from the yt-dlp GitHub releases page.
    2. Open a terminal.
    3. Make the file executable:
      bash
      chmod +x /path/to/yt-dlp
      (Replace /path/to/yt-dlp with the actual path).
    4. Move the file to a directory in your PATH (usually /usr/local/bin/):
      bash
      sudo mv /path/to/yt-dlp /usr/local/bin/
    5. Ensure ffmpeg is installed as well:
      bash
      ffmpeg -version # Check if ffmpeg is present
      If not installed use the appropriate command for you system from part A above.

2. Basic Usage

The most basic command to download a video is:

bash
yt-dlp "URL_OF_VIDEO"

Replace "URL_OF_VIDEO" with the actual URL of the video you want to download. For example:

bash
yt-dlp "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

This will download the video in the best available quality (both video and audio combined) and save it in the current directory with a default filename.

3. Common Options and Examples

yt-dlp has a huge number of options. Here are some of the most useful ones:

  • -f, --format <FORMAT>: Select specific video and audio formats.

    • List available formats:
      bash
      yt-dlp -F "URL_OF_VIDEO"
      This will output a table of available formats, each with a format code (e.g., 22, 137, 140). The table shows video resolution, codec, audio codec, and filesize estimates.
    • Download a specific format (e.g., format code 22):
      bash
      yt-dlp -f 22 "URL_OF_VIDEO"
    • Download the best video and audio separately, then merge them (requires ffmpeg):
      bash
      yt-dlp -f "bestvideo+bestaudio/best" "URL_OF_VIDEO"
      This is often necessary to get the highest quality, as YouTube often stores the best video and audio streams separately. The /best part acts as a fallback if the best combined format is available.
    • Download only audio in mp3 format:
      bash
      yt-dlp -x --audio-format mp3 "URL_OF_VIDEO"

  • -o, --output <TEMPLATE>: Specify the output filename or a template.

    • Save with a specific filename:
      bash
      yt-dlp -o "my_video.mp4" "URL_OF_VIDEO"
    • Use a template:
      bash
      yt-dlp -o "%(title)s-%(id)s.%(ext)s" "URL_OF_VIDEO"
      This uses placeholders:

      • %(title)s: Video title.
      • %(id)s: Video ID.
      • %(ext)s: File extension.
      • Other placeholders are: %(uploader)s, %(upload_date)s, %(playlist_title)s, %(playlist_index)s, etc.
      • You can create subfolders using path separators in the template:
        bash
        yt-dlp -o "Downloads/%(uploader)s/%(title)s-%(id)s.%(ext)s" "URL_OF_VIDEO"

  • -x, --extract-audio: Extract only the audio.

    bash
    yt-dlp -x "URL_OF_VIDEO"
    This will download and convert the audio to an Opus file by default.

  • --audio-format <FORMAT>: Specify the audio format (requires -x).
    bash
    yt-dlp -x --audio-format mp3 "URL_OF_VIDEO"
    Common audio formats: mp3, m4a, wav, flac, opus.

  • --audio-quality <QUALITY>: Set quality of audio.
    bash
    yt-dlp -x --audio-format mp3 --audio-quality 0 "URL_OF_VIDEO" # best quality
    yt-dlp -x --audio-format mp3 --audio-quality 5 "URL_OF_VIDEO" # medium quality
    yt-dlp -x --audio-format mp3 --audio-quality 9 "URL_OF_VIDEO" # worst quality

  • --download-archive <FILE>: Keep track of downloaded videos.

    bash
    yt-dlp --download-archive archive.txt "URL_OF_VIDEO"
    This creates a file named archive.txt. yt-dlp will check this file before downloading and skip any video that’s already listed in the archive. Useful for avoiding re-downloading videos.

  • --playlist-start <NUMBER>, --playlist-end <NUMBER>, --playlist-items <ITEM_SPEC>: Download parts of a playlist.

    • Download from the 5th video onwards:
      bash
      yt-dlp --playlist-start 5 "URL_OF_PLAYLIST"
    • Download only the first 10 videos:
      bash
      yt-dlp --playlist-end 10 "URL_OF_PLAYLIST"
    • Download videos 1, 3, 5, 7, and 9-12:
      bash
      yt-dlp --playlist-items 1,3,5,7,9-12 "URL_OF_PLAYLIST"
    • Download an entire playlist:
      bash
      yt-dlp "URL_OF_PLAYLIST"

  • --limit-rate <RATE>: Limit the download speed (e.g., 100K, 2.5M).

    bash
    yt-dlp --limit-rate 500K "URL_OF_VIDEO"

  • --cookies <FILE>: Use cookies from a browser to access age-restricted or private videos.

    1. Install a browser extension to export cookies (e.g., “Get cookies.txt” for Chrome/Firefox).
    2. Log in to the site (e.g., YouTube) in your browser.
    3. Use the extension to export the cookies to a file (e.g., cookies.txt).
    4. Use the --cookies option:
      bash
      yt-dlp --cookies cookies.txt "URL_OF_VIDEO"
    5. Important: Be careful with your cookies. Do not share the cookies.txt file.

  • -v, --verbose: Show detailed output during the download.

    bash
    yt-dlp -v "URL_OF_VIDEO"
    Helpful for debugging.

  • --write-subs: Download subtitles.
    bash
    yt-dlp --write-subs "URL_OF_VIDEO"

  • --sub-langs: Specify which subtitle languages to download.

    bash
    yt-dlp --write-subs --sub-langs en,fr "URL_OF_VIDEO" # English and French
    yt-dlp --write-subs --sub-langs all,-live_chat "URL_OF_VIDEO" # All except live chat

  • --embed-subs: Embed subtitles into the video file (if the container format supports it, like MKV).
    bash
    yt-dlp --embed-subs -f "bestvideo+bestaudio/best" "URL_OF_VIDEO"

  • --write-thumbnail: Download the video thumbnail.
    bash
    yt-dlp --write-thumbnail "URL_OF_VIDEO"

  • --embed-thumbnail: Embed the thumbnail into the audio file (for audio-only downloads).
    bash
    yt-dlp -x --embed-thumbnail --audio-format mp3 "URL_OF_VIDEO"

4. Configuration File

You can create a configuration file to store commonly used options, avoiding the need to type them every time. Create a file named yt-dlp.conf (or config on Windows without an extension) in one of these locations:

  • Windows: %APPDATA%\yt-dlp\config or in the same directory as yt-dlp.exe.
  • macOS/Linux: ~/.config/yt-dlp/config or /etc/yt-dlp.conf.

Example yt-dlp.conf file:

“`

Always merge the best video and audio

-f bestvideo+bestaudio/best

Use a specific output template

-o %(title)s-%(id)s.%(ext)s

Download subtitles and embed them

–write-subs
–embed-subs
–sub-langs en,es

Limit download rate

–limit-rate 1M

Use a download archive

–download-archive ~/.config/yt-dlp/archive.txt

Extract Audio in mp3 by default

-x
–audio-format mp3
“`

Options in the command line will override those in the config file.

5. Updating yt-dlp

yt-dlp is frequently updated. To update it, use:

bash
yt-dlp -U

If you installed via a package manager, use your package manager’s update command (e.g., apt update && apt upgrade, brew upgrade, choco upgrade yt-dlp).

6. Troubleshooting

  • “ERROR: unable to download video data: HTTP Error 403: Forbidden”: This often means the video is age-restricted or private. Try using the --cookies option. It may also indicate an issue with your IP address or network; try again later or use a VPN.

  • “ERROR: requested format not available”: The requested format (using -f) doesn’t exist for that video. Use -F to list the available formats.

  • “WARNING: unable to extract uploader nickname”: This is usually harmless and can be ignored.

  • Download speed is slow: Try using the --limit-rate option without a limit to see if it’s your internet connection. If it’s still slow, it might be the server hosting the video.

  • ffmpeg errors: Make sure ffmpeg is correctly installed and in your PATH. yt-dlp relies on ffmpeg for merging streams and converting audio.

  • Check the GitHub issues page: If you encounter a persistent problem, search the yt-dlp GitHub issues page to see if others have reported the same issue and if there’s a solution.

This comprehensive guide should provide a solid foundation for using yt-dlp. Remember to consult the official documentation (by running yt-dlp --help) for a complete list of options and further details. Happy downloading!

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top