Page Body

Download Media With yt-dlp

Often, it is convenient to have a local copy of media that you would like to access. You may be in an area that does not have a strong Internet connection, or any connection at all, so having local copies can be a boon when streaming is not viable. Also, you may want to keep a content copy for archival purposes.

Using a content provider's download options can be inefficient. A Command Line Interface (CLI) tool called yt-dlp can help you streamline the download process.

Note: If you are not familiar with the GNU/Linux command line interface, review the Conventions page before proceeding.


You can install yt-dlp from PyPI, the Python Package Index. pip (pip installs packages) is the package installer for Python. By default, it is configured to use PyPI.

Depending on your GNU/Linux distribution, you may need to install pip before proceeding:

# apt install python3-pip (Debian)

# dnf install python3-pip (Fedora)

When installing new software via pip, it is often best to do so within a virtual environment. After creating and activating a virtual environment, you can install yt-dlp:

python3 -m pip install yt-dlp


By default, the yt-dlp command will save its output to the directory that you issue the command from. You can change this by creating a yt-dlp configuration file and specifying a new download directory/output file format:

$ mkdir -p "${HOME}/.config/yt-dlp" &&
        echo '# Save media to Downloads directory in your home directory'
        echo '-o "${HOME}/Downloads/%(title)s.%(ext)s"'
    } > "${HOME}/.config/yt-dlp/config"

The above command will create the yt-dlp directory in ${HOME}/.config/ (if this directory does not exist on your system, the -p option will ensure that it is created), create a config file in that directory, and add lines to the config file to have the yt-dlp command download media to your home directory's Downloads directory. Files will be saved with the media content's title and extension as the filename.


It is important to keep your software up-to-date. If you followed the prior installation instructions, you can upgrade yt-dlp after virtual environment activation like so:

python3 -m pip install -U yt-dlp

If you have your own alias for updating your system, you may want to add the appropriate commands for keeping yt-dlp up-to-date.


yt-dlp should work with a vast amount of sites. Also, the command is highly configurable through myriad options. You can customize your commands to alter output filenames with filename templates and specify which video/audio format to obtain.

To see if multiple formats are available for a given piece of media, you can use yt-dlp's -F (--list-formats) option. For example:

$ yt-dlp -F \
[PeerTube] 0a6feebf-a2d6-4965-9942-34bf63d92054: Downloading JSON metadata
[info] Available formats for 0a6feebf-a2d6-4965-9942-34bf63d92054:
format code  extension  resolution note
480p         mp4        480p       80.12MiB
1080p        mp4        1080p      190.49MiB (best)

However, it is simplest to let the yt-dlp command select the best format of a given piece of content for you. You can use the following special names to select the case formats:

  • b Selects the best quality format represented by a single file with both video and audio
  • bv Selects the best quality video-only format (may not be available)
  • ba Selects the best quality audio-only format (may not be available)

Then, if you just want the best quality format file available that has both video and audio in a single file, you can use a command like this (the -f option is short for --format):

yt-dlp -f 'b' ''

Some media providers keep the best quality video and audio in separate video-only and audio-only files, respectively. There is a way to utilize yt-dlp to create a combined best quality file from these disparate files.

First, make sure that you have ffmpeg installed. This program is likely available in the repository of your GNU/Linux distribution (if not, you may need to add/enable an additional repository to obtain it).

For example, here is how you can install ffmpeg on Debian:

# apt install ffmpeg

Then, you can obtain the best video-only file, the best audio-only file, and merge them into a single file with both video and audio like so:

yt-dlp -f 'bv[ext=mp4]+ba[ext=m4a]/b[ext=mp4]/b' ex_url...

You can find more examples regarding comparable commands in yt-dlp's documentation.

If you encounter a media provider that only has video file formats available, and you only want the video's audio, you can use yt-dlp to download the video, extract the audio, and provide an audio-only file. This will require ffmpeg, as well.

To obtain just the audio from a file with both video and audio, you can use yt-dlp's -x (--extract-audio) option:

yt-dlp -f 'b' -x ex_url...

Multiple Downloads

Running yt-dlp commands is fine for an occasional download, but if you ever need to download multiple files in a short period of time, it can become tedious.

The following is a Bash script that can improve this process:

The script gives you the opportunity to continually add URLs for media that you would like to download. By default, the script is set to download the best quality format represented by a single file with both video and audio (i.e., -f 'b'). However, you can change this via the script's options.

For example, if you want to switch from video to audio content, call the script with the -a (--audio) option. If you want the best quality *-only formats, use the -g (--greatest-quality) option.

Some content providers also create separate subtitle files (e.g., yt-dlp --list-subs ex_url... lists the available subtitles for each video). It can be useful to download the subtitles too and embed them into the video content. If you want to enable this, use the -s (--subtitles) script option. By default, the script is set to use en-US as the subtitle language, but this can be changed by updating the script's sub_lang variable.

After the script starts, it displays a heading with the chosen output mode and a prompt. At the latter, you can either continually enter URLs to download or enter q to quit.

yt-dlp's output has been suppressed to prevent the script from being disrupted. If yt-dlp wrote any information to the standard error during execution, the script will print the log file path to your terminal before it exits. If a log path is printed, it may mean that either something went wrong and the requested content was not properly downloaded, or that yt-dlp output diagnostic information that may (or may not) be helpful to you or the program's developer.


For more information on yt-dlp, check out its man page by running man 1 yt-dlp or visit its project repository.

Enjoyed this post?

Subscribe to the feed for the latest updates.