Nowadays a lot of video sharing platforms exist online. Some are really popular, like Youtube , and others are a little more “obscure”. Different types of content can be found on these platforms, but is not always possible to download them via the native web interface. In this tutorial we will see how to use a small command line utility: youtube-dl. This command line utility is able to download said videos for us using a very simple syntax. The following tutorial aims to demonstrate the capabilities of the program, however it should be used only where appropriate, in order to respect copyright laws.

In this tutorial you will learn:

  • How to install youtube-dl
  • How to download videos using youtube-dl
  • How to list the available formats for a video
  • How to download a specific format
  • How to stream a video directly to a media player
  • How to save downloaded files using template patterns
  • How to specify options into the youtube-dl configuration file
How to download online videos from the command line using Youtube-dl
How to download online videos from the command line using Youtube-dl

Software requirements and conventions used

Software Requirements and Linux Command Line Conventions
Category Requirements, Conventions or Software Version Used
System Distribution independent
Software youtube-dl
Other None
Conventions # - requires given linux-commands to be executed with root privileges either directly as a root user or by use of sudo command
$ - requires given linux-commands to be executed as a regular non-privileged user


Youtube-dl is a small command line utility written in Python. The software supports a lot of online video sharing platforms (here is the complete list of supported sites) and is available in the repository of the most used Linux distributions such as Fedora, Debian (and its derivatives) and Archlinux. Installing it is just a matter of invoking the package manager of our favorite distro. On Fedora, for example we would run:

$ sudo dnf install youtube-dl

On Debian, instead, we would run the following command:

$ sudo apt-get update && sudo apt-get install youtube-dl

On Archlinux, the package is contained in the the community repository. To install it via pacman we would run:

$ sudo pacman -Sy youtube-dl

Being a software developed in Python is also possible to obtain it via the programming language package manager, pip. To install the application only for the current user, for example, we could run the following command (no administrative privileges needed):

$ pip install youtube-dl --user

Basic usage

Using youtube-dl is very simple. Its basic syntax is the following:

youtube-dl [OPTIONS] URL

Subscribe to RSS and NEWSLETTER and receive latest Linux news, jobs, career advice and tutorials.

Say for example we want to to download a video from the Air Mozilla platform. All we have to do is to invoke the program and pass the video URL as argument:

$ youtube-dl
[generic] Viewer: Requesting header
WARNING: Falling back on generic information extractor.
[generic] Viewer: Downloading webpage
[generic] Viewer: Extracting information
[download] Destination: /home/egdoc/Videos/The Joy of Coding - Episode 237 - January 13, 2021.mp4
[download] 100% of 1.84GiB in 06:08

After launching the command above, we should find the video file inside our working directory.

Listing the available video formats

By default youtube-dl, tries to download the best available format for the specified video. In some cases, however, we may want to obtain the list of all the available ones. All we have to do to accomplish said task is to invoke the application with the -F option, (short for --list-formats). Let’s see an example using a Youtube URL (the video is from the channel):

$ youtube-dl -F
[youtube] IyOcjK3pa4w: Downloading webpage
[youtube] IyOcjK3pa4w: Downloading MPD manifest
[info] Available formats for IyOcjK3pa4w:
format code  extension  resolution note
251          webm       audio only DASH audio    3k , webm_dash container, opus @160k (48000Hz)
139          m4a        audio only DASH audio   49k , m4a_dash container, mp4a.40.5@ 48k (22050Hz)
140          m4a        audio only DASH audio  130k , m4a_dash container, mp4a.40.2@128k (44100Hz)
134          mp4        570x360    DASH video   15k , mp4_dash container, avc1.4d401e, 30fps, video only
136          mp4        1142x720   DASH video   54k , mp4_dash container, avc1.64001f, 30fps, video only
278          webm       228x144    DASH video   95k , webm_dash container, vp9, 30fps, video only
160          mp4        228x144    DASH video  108k , mp4_dash container, avc1.4d400b, 30fps, video only
242          webm       380x240    DASH video  220k , webm_dash container, vp9, 30fps, video only
133          mp4        380x240    DASH video  242k , mp4_dash container, avc1.4d400c, 30fps, video only
243          webm       570x360    DASH video  405k , webm_dash container, vp9, 30fps, video only
244          webm       760x480    DASH video  752k , webm_dash container, vp9, 30fps, video only
135          mp4        760x480    DASH video 1155k , mp4_dash container, avc1.4d400a, 30fps, video only
247          webm       1142x720   DASH video 1505k , webm_dash container, vp9, 30fps, video only
18           mp4        570x360    360p  110k , avc1.42001E, 30fps, mp4a.40.2@ 96k (44100Hz), 280.25KiB
22           mp4        1142x720   720p  169k , avc1.64001F, 30fps, mp4a.40.2@192k (44100Hz) (best)

The output of the command is very well formatted. We can easily spot the video extension, the video resolution, the encoding used, and also the file size.

How can we specify the format we want to download? All we have to do is to invoke youtube-dl again, but this time we the -f option (lowercase), which is the short for --format, and reference the format we want to download providing the format code reported in the first column of the output above as its argument. Say for example we want to download the 570x360 version of the video, with the mp4 extension; we would run:

$ youtube-dl -f 18
[youtube] IyOcjK3pa4w: Downloading webpage
[youtube] IyOcjK3pa4w: Downloading MPD manifest
[download] Destination: Printing Message on Screen using named pipe and Bash shell - Example 01-IyOcjK3pa4w.mp4
[download] 100% of 280.25KiB in 00:00

It is also possible to download all available formats by invoking youtube-dl with the --all-formats options, or instruct the application to prefer free formats by using --prefer-free-formats.

Obtaining only the audio track

Sometimes we may want to obtain only the audio track for the specified video source. In those cases we can do two things: the first is to download the audio only format if available. Sticking to the output of previous example, to download the opus audio track, we would run:

$ youtube-dl -f 251

The second, more general solution, is to extract the audio from the video track. To perform said operation, we have to invoke youtube-dl with the -x option (--extract-audio). For the extraction to work correctly, we should have ffmpeg and ffprobe (or avconv and avprobe) installed on our system. To extract the audio for the URL we are using as an example we would run:

$ youtube-dl -x

What if we want to specify the audio format for the extracted track? All we have to do is to use the --audio-format option. This option has sense only if used with -x. We can choose the audio format among: “best” (the default), “aac”, “flac”, “mp3”, “m4a”, “opus”, “vorbis”, “wav”. To obtain a “flac” file, for example, we would run:

$ youtube-dl -x --audio-format flac

When we use the -x option, the video file is downloaded and then the conversion is performed to obtain the audio track. Once the conversion is done, the video file is automatically removed. In case we want to keep it, we can use the -k option (short for --keep-video).

Stream a video directly to a media player

Another very nice feature of youtube-dl is the ability to stream a video directly to a specified media player. All we have to do to achieve the functionality is to instruct youtube-dl to stream media to stdout (standard output) and than invoke a media player capable of reading from stdin (standard input). We can use a shell pipe to perform the operation. Supposing we are using vlc, we would run:

$ youtube-dl -o - | vlc -

If everything goes as expected, the video player will be launched, and the specified video will be streamed after a small buffering time.

Saving videos in a specific directory

When we download a file we may need to specify a directory where it should be downloaded which is not our current working directory. To perform such operation we can make use of the -o option. For example, to download the file into the ~/Videos directory we could run:

$ youtube-dl -o '~/Videos/%(title)s.%(ext)s'

Let’s see what we did in the example above. The -o option let us specify a sort of “template” system to specify how to save a downloaded file. In our example we specified that the file should be downloaded inside the ~/Video directory and the file should be named after the video title followed by a dot and by the video extension. Each element of the template must be specified by a percent symbol (%) followed by the element in parentheses and by formatting operations: in this case we used an s so we instruct to format the elements as a string. In this case the file will be saved as:

'/home/egdoc/Videos/The Joy of Coding - Episode 237 - January 13, 2021.mp4'

There are various elements which can be used to construct a file name. A few examples:

Names Meaning
id Identifier of the video
title The video title
ext The video filename extension
uploader The name of the video uploader
channel The name of the channel hosting the video

Using the configuration file

Instead of specifying the wanted options each time we invoke youtube-dl, we can set them once inside its configuration file, so they are automatically used. Youtube-dl looks for a system-wide configuration file at /etc/youtube-dl.conf, and for a per-user file at ~/.config/youtube-dl.conf. The files may not exist by default, so we may need to create them.

Inside the file, the lines starting with a # symbol are considered as comments, and the desired options must be specified one per line. For example, to always adopt the download pattern we used in the previous example, inside the configuration file, we could simply write:

# Download using the specified pattern
-o '~/Videos/%(title)s.%(ext)s'


In this tutorial we learned the basic usage of the youtube-dl command line utility. The program can be used to download videos from several video sharing platforms. We saw how to install it using the package managers of the most used Linux distributions and via pip. We saw how to download a video, how to list all the available formats, and how to instruct the application to download a specific one. We also saw how to stream a video directly to a media player and how to download it and save it using a series of template elements. Again, one very important thing to remember is that the application should be only used to download videos where permitted, to be sure not to infringe any copyright law.

Submit your RESUME, create a JOB ALERT or subscribe to RSS feed.
Subscribe to NEWSLETTER and receive latest news, jobs, career advice and tutorials.
Get extra help by visiting our LINUX FORUM or simply use comments below.

Comments and Discussions