Lots of people download videos from YouTube, either for just saving later, or using them as part of something else.
Lots of people also don't understand what they're doing at all and end up using downloader sites.

Downloader sites range from decent (Y2Mate) to horrible (someone told me they used this site when I asked them what site was messing up videos they were downloading).

The problem with downloader sites is a combination of things, but typically it comes down to these:
- They compress your videos, they aren't lossless
- They often introduce errors into the video files

For these reasons, you should avoid using online downloaders for YouTube videos.

The aim of this article is to teach you the correct way of downloading YouTube videos with youtube-dl and giving you the information you need to make intelligent choices while using it. The article is structured to give quick answers to common problems and needs, but I encourage you to read all the sections to learn more about youtube-dl and YouTube ripping in general.

Table of Contents

Installing youtube-dl
- Download and install
- Updating

Downloading videos
- A note about VPNs
- Where videos are downloaded
- Basic video download
- Downloading specific qualities
- Downloading qualities by criteria
- Downloading a video's audio only
- Downloading a video and all of its metadata
- Downloading livestreams
- Downloading premium and user-locked videos
- Downloading subscriptions
- Cancelling downloads
- Resuming downloads

Output filename structure
- Typical files
- Unfinished files

Video formats and containers
- Difference between a format, a container, and a file extension
- Web-friendly containers
- Don't be afraid of MKV

Media players
- Recommended media players
- Media players you shouldn't use

- Failed to extract video metadata
- Did not get any data blocks
- HTTP Error 429: Too Many Requests

Further reading


Installing youtube-dl

youtube-dl (alernate links: #1, #2, #3) is a tool used for downloading YouTube videos, along with videos from other sites as well. It will download YouTube videos at their highest quality by default, and not convert. This preserves videos' original quality on YouTube.

Download and install


You often have to update youtube-dl because sites like YouTube change their code very often and break the program's functionality, requiring you to update the tool.

Downloading videos

Youtube-dl is a command-line program, so all examples in this section need to be run in a command line of some sort, either a terminal on Linux & MacOS, or in Windows Command Prompt or PowerShell.

All download commands can accept a single video URL, channel, playlist, and more.

A note about VPNs

As a tool that interacts with external websites, youtube-dl's behavior isn't concrete and is at the mercy of the site it's interacting with. With that said, the way youtube-dl connect to YouTube is important.
Using youtube-dl while using a VPN usually works, but sometimes ends up causing issues. YouTube tends to treat VPN users worse because they look less human, and more like bots. For this reason, it's recommened that you disconnect from your VPN if you encounter issues while using it.

If you still need to use a VPN with it, consider switching to another VPN location, or run it with your browser cookies as explained in the Downloading premium and user-locked videos section.

Where videos are downloaded

Videos are downloaded to whatever your current commandline/terminal location is. By default, this is your home folder. Regardless of your platform, you can change the current folder by typing the following:
cd <new location>
This will change your folder to the provided location, and until you close that commandline/terminal or change the location again, videos will be downloaded there.

Additionally, it's worth noting that there is no way to define a default download location, this process is necessary each time you open a new commandline/terminal.

Basic video download

The most basic command in youtube-dl is providing it with a single URL to download:
youtube-dl "<URL>"
This command will download the video provided at the highest quality possible. This works on both singular videos, OR playlists, entire channels, and more.
Keep in mind that if you're specifying a YouTube video and it's from a playlist, youtube-dl will download the entire playlist and not just the video, so be careful not to give it a playlist by accident when you meant to download only one video.

EDIT 07/01/2021: Someone has told me that this didn't happen when they provided a video that was from a playlist, so if it only downloads the singular video for you, go to the playlist page and use that URL instead.

Downloading specific qualities

You can download a specific video quality, or even download a video's audio only if you like.

The first thing you need to do is see which qualities are available to you:
youtube-dl -F "<URL>"
This will produce something similar to the following:
[info] Available formats for B9RbCdSNoQg:
format code  extension  resolution note
249          webm       audio only tiny   64k , opus @ 50k (48000Hz), 11.22MiB
250          webm       audio only tiny   81k , opus @ 70k (48000Hz), 15.23MiB
140          m4a        audio only tiny  132k , m4a_dash container, mp4a.40.2@128k (44100Hz), 27.84MiB
251          webm       audio only tiny  152k , opus @160k (48000Hz), 29.42MiB
394          mp4        256x144    144p   91k , av01.0.00M.08, 30fps, video only, 13.16MiB
278          webm       256x144    144p   97k , webm container, vp9, 30fps, video only, 14.80MiB
160          mp4        256x144    144p  191k , avc1.4d400c, 30fps, video only, 10.52MiB
395          mp4        426x240    240p  218k , av01.0.00M.08, 30fps, video only, 18.97MiB
242          webm       426x240    240p  224k , vp9, 30fps, video only, 20.16MiB
133          mp4        426x240    240p  328k , avc1.4d4015, 30fps, video only, 19.31MiB
396          mp4        640x360    360p  401k , av01.0.01M.08, 30fps, video only, 32.84MiB
243          webm       640x360    360p  411k , vp9, 30fps, video only, 33.20MiB
134          mp4        640x360    360p  603k , avc1.4d401e, 30fps, video only, 34.05MiB
397          mp4        854x480    480p  735k , av01.0.04M.08, 30fps, video only, 55.80MiB
244          webm       854x480    480p  756k , vp9, 30fps, video only, 50.42MiB
135          mp4        854x480    480p 1025k , avc1.4d401f, 30fps, video only, 49.43MiB
398          mp4        1280x720   720p 1497k , av01.0.05M.08, 30fps, video only, 114.65MiB
247          webm       1280x720   720p 1515k , vp9, 30fps, video only, 88.29MiB
136          mp4        1280x720   720p 2238k , avc1.4d401f, 30fps, video only, 85.67MiB
399          mp4        1920x1080  1080p 2630k , av01.0.08M.08, 30fps, video only, 205.52MiB
248          webm       1920x1080  1080p 2664k , vp9, 30fps, video only, 231.49MiB
137          mp4        1920x1080  1080p 6149k , avc1.640028, 30fps, video only, 287.57MiB
18           mp4        640x360    360p  456k , avc1.42001E, 30fps, mp4a.40.2@ 96k (44100Hz), 98.10MiB
22           mp4        1280x720   720p  527k , avc1.64001F, 30fps, mp4a.40.2@192k (44100Hz) (best)    
It's important to explain the columns in the table the command just spit out.

format code is the key for this format. When specifying which to download, that's what will be used to select.
extension defines the container (not format) the quality is stored in.
resolution is fairly self-explanatory, it defines the video resolution, or is audio only if the file isn't video.

note is more ambiguous, but contains some of the most important information.
The first value in this column is the height of the video, or tiny if it's audio only.
The second is the video or audio's bitrate. It's one of the best indicators of quality, but in the case of video, the size required for good quality gets higher as resolution increases.
The remaining data is information about the formats in the container file. Its format for audio only is:
<audio format> @ <bitrate>k (<full bitrate>Hz), <file size>MiB/KiB
Its format for video only is:
<video format>, <frame rate>fps, video only, <file size>MiB/KiB
And its format for video + audio is:
<video format>, <frame rate>fps, <audio format> @ <bitrate>k (<full bitrate>Hz), <file size>MiB/KiB
Keep in mind that not all qualities listed contain both video and audio, and to get the best quality, youtube-dl often has to merge multiple formats together. To the best of my knowledge, the quality that youtube-dl lists as (best) here is the best bitrate and resolution file that has both audio and video, but is not the best combination of video-only and audio-only files.

To download one of these qualities, find its format code, and run the following:
youtube-dl -f <format code> "<URL>"
This will download the specified quality. If you want to download a video with a specific video and audio quality, you can use the + operator to combine them. For example, the following will download specific video and audio qualities, and merge them into one file:
youtube-dl -f "<video format code>+<audio format code>" "<URL>"
If the video and audio formats aren't compatible, they will be merged into a single MKV file.

Additionally, you cannot specify more than one video and audio quality.

Downloading qualities by criteria

You can download videos in a quality specifed by a criteria such as resolution, bitrate, extension, etc.

Specifying quality by criteria is done by replacing format codes with either best (to get the best audio + best video, cannot be combined with another criteria), bestvideo (best video), or bestaudio (best audio). You can also add further qualifications on these terms, such as extension, resolution, etc.

The youtube-dl README has an entire section dedicated to selecting qualities (format selection), and as such, it would be a waste to write an inferior guide here. You should read the official one for this.

Downloading a video's audio only

You can download a video's audio only if you like. This is useful for downloading music, podcasts, and only audio-only content where having video along with the audio would be wasteful.

The following is an example of downloading a video's audio at the best quality available:
youtube-dl -f "bestaudio" <URL>
This will download the best quality, but the result may not be in a typical audio container. If you want to download the audio with a specific extension, you can specify it like so:
youtube-dl -f "bestaudio[ext=m4a]/bestaudio" <URL>
This will try to download the best audio with the extension m4a. The /bestaudio in the example tells youtube-dl to go for the best quality if no quality with the extension m4a exists. Without this, it would simply fail if it couldn't find the preferred extension.

Downloading a video and all of its metadata

There may come a time when you want to download not only a video, but also its metadata, thumbnails etc. This comes up a lot when you need to achive a video and all info about it.

The following command will download a video, its metadata, thumbnails, annotations (this may or may not work anymore) and subtitles:
youtube-dl --write-annotations --write-description --write-info-json --write-all-thumbnails --write-sub --add-metadata --embed-subs -i <URL>
The resulting files will be in the same format as normal files, except their extensions will be different from the video. For example, the metadata will have the extension json.

Downloading livestreams

You can download livestreams like any other type of video. Archived livestreams are handled just like normal videos, and current livestreams will be downloaded live, and merged into a single file once the stream ends or youtube-dl is stopped.

You can download livestreams on Twitch as well as YouTube.

Downloading premium and user-locked videos

You can download premium content such as YouTube Premium shows or movies you bought from YouTube movies with youtube-dl, and user-locked content such a private videos as well.

To do this, you need to sign into YouTube and extract your browser cookies. Extracting your cookies can be done with a browser extension called ExportCookies.

Firefox Add-On
Chrome Extension
Source Code

Once you're signed into YouTube and have the extension installed, click the extension's icon in a YouTube tab and click all domains. Save the cookies.txt file where you want to use youtube-dl.

When you have the cookies.txt file, you can specify it along with the URL of the video you want to download:
youtube-dl --cookies cookies.txt <URL>
The video should be able to download.

I have seen this feature break with recently with new YouTube video safeguards, so I can't guarantee this will work, but it has worked in the past.

Downloading subscriptions

Years ago, you were able to log into YouTube with youtube-dl and download videos directly from your subscriptions page, but at the time of writing, that doesn't seem to work anymore. You can also try downloading your subscriptions page while specifying cookies using the last section's guide, but it didn't work at the time of writing either.

Another possibly alternative is this project on GitHub.

Cancelling downloads

To cancel a download, press CTRL+C on the terminal/commandline where youtube-dl is currently running. It will cancel the download. Partially downloaded files will still be present unless you delete them.

Resuming downloads

If the program closes mid-download, you can resume by making sure your terminal/commandline is in the same location as the partially downloaded video, and then running the download command you used. It will continue where it left off and not require re-downloading anything.

Output filename structure

The names of files downloaded by youtube-dl are name random, and have a structure that is useful if you understand it.

Typical files

Here's a typical youtube-dl video filename:
Stories From Our Disturbing World _ Episode 1-B9RbCdSNoQg.mkv
This example was a video named Stories From Our Disturbing World | Episode 1, and the filename reflects that, except for the character | being changed into _. This change is because some characters cannot exist in filenames, so youtube-dl is smart enough to replace them with something that is valid. It's worth mentioning that it doesn't do this with unicode characters like Chinese characters or accented letters, because those types of characters can still exist in filenames.

Next to the title, we see a dash (-) and then what appears to be a random string of characters. This is the video ID. Everything after the dash in youtube-dl is the video's ID. This will be different depending on the site, but in this example, this was a video downloaded from YouTube.

Unfinished files

While youtube-dl is downloading files, the filename structure will be different.
Here's an example of a downloading/unfinished file:
Stories From Our Disturbing World _ Episode 1-B9RbCdSNoQg.f137.mp4.part
Like the example in the previous sub-section, the video title is present and bad characters are replaced with _, and the ID is present. However, after the ID, there is a period (.) and another string of seemingly random numbers starting with an f. These numbers are actually the format code of the file being downloaded. The last notable part of the filename is that it ends with .part. This signifies that the file has not finished downloading yet.

Video formats and containers

There are very long and technical things you can read about formats and containers, but I will try to condense the most important points into this section.

Difference between a format, a container and a file extension

The terms format, container, and file extension are often used interchangeably, but there are important differences between them.

A format is a way a piece of media is encoded. Examples include AVC (video used in most MP4s), AAC (audio used in most MP4s), and VP9 (video used in most WebMs), just to name a few.
Formats themselves aren't files, they are stored in containers.

A container is a file format that can house audio and/or video, among other things such as subtitles, cover images, etc. They aren't the encoded media themselves, but they contain them. They will have a specific file extension or extensions associated with them. Examples include WebM, MP4, Matroska (MKV), and MOV (QuickTime), to name a few.

In the context of media, a file extension is simply a piece of text to classify which container a media file is using. So for example, the extension mkv is associated with the Matroska container.

Web-friendly containers

The following are a set of containers that will play on modern web browsers. The list is not exhaustive, but the types on here are what you will often encounter most often while dealing with youtube-dl:

Don't be afraid of MKV

When you download a video without specifying the quality using youtube-dl, it often needs to merge audio and video formats into a file, even if they typically don't go together. For example when downloading a video, it finds that WebM (Opus) audio has the highest quality, but an MP4 (AVC) video has the highest resolution. An MP4 file cannot store WebM video, and a WebM file cannot store MP4 video. So what can it do? It uses a container format called Matroska, or MKV, that can house a diverse range of video and audio formats, among other things.

Many people have never seen MKV files, or at least have never used them, and it drives a lot of them to try to convert the files to familiar formats like MP4.

Media players

A very important part of dealing with video and audio is having a media player that will handle any format and container you throw at it. This section briefly goes over media players and which ones I recommend, and which ones I specifically would avoid.
I recommend VLC and MPV as media players for all formats.

I use MPV primarily because of its minimalism, speed, and high quality decoder. I use VLC for DVDs and any sort of interactive video. Most people will prefer VLC over MPV, so they should use it unless they are willing to use MPV, which has a very minimal GUI and is mostly keyboard-driven. If you have issues with video glitches/artifacts while using VLC, you should use MPV, as it has better decoders. VLC supports pretty much every file you can think of, but in cases where it doesn't, MPV will, so I recommend having both players installed on your computer.

Additionally, if you use Android, you can use VLC on there too, although I prefer MX Player for its customizability and fine-grained control.

Media players you shouldn't use

The header says "Media players", but the only player I would genuinely recommend against using is Windows Media Player. It has poor support for many modern formats, and its support varies significantly between versions of Windows.

If I discover are any other media players as bad as this, I'll be sure to update this section.


(Possible) solutions to a non-exhaustive list of common issues.

Failed to extract video metadata

If this happens, most likely YouTube updated, and you need to update youtube-dl.

Did not get any data blocks

This seems to happen to only certain people in my experience. If you are using a VPN, disable it and try it again.

You can try to download at another quality if nothing else works. You can try to use the bestvideo+bestaudio format code:
youtube-dl -f bestvideo+bestaudio <URL>

HTTP Error 429: Too Many Requests

This error occurs when the IP address you're using has made several requests to YouTube. This is usually a problem that happens to VPN users. The best thing you can do to solve this problem is disconnect from any VPNs you're using and try again.

If you aren't using a VPN, or can't solve this problem otherwise, there are some other possible methods that might help. One method that was suggested by a StackOverFlow user is adding the --force-ipv4 or possibly --force-ipv4 option when downloading.
Another suggestion was dumping your browser cookies and specifying them when downloading videos. See the Downloading premium and user-locked videos section to learn how to do this.

I haven't personally tried either of these two methods, but you're free to give them a go and see if they help you.

Further Reading

I recommend you read the following if you would like to know more about this topic:

youtube-dl README - Has a huge set of examples on how to use youtube-dl, among other stuff such as the FAQ


Artifact - A visual anomaly in videos or images, often caused in video by encoding or decoding issues

Format - A specific way of encoding a piece of media

Container/Container Format - A file format that contains multiple encoded media formats, such as video and audio, or even subtitles

File extension - The simple text following a dot (.) at the end of a file (for example: .mp4). In the context of media, this corresponds to media containers and sometimes formats.

Lossless - A type of media that has not lost any quality after being encoded, often at the cost of a larger size

Lossy - A type of media that has lost some quality after being encoded, often being smaller than the original

Compress - To make a piece of media smaller, either by making storage more efficient (in the case of lossless compression), or by losing some quality (in the case of lossy compression)

Encode - To process a piece of media into a format that a computer can understand, often associated with compression