YouTube video ripping mega guide

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.

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.

In the previous section, I mentioned that YouTube treats VPNs differently than normal connection. The same thing applies to downloading videos on servers. The IP addresses used on servers show up as datacenter IPs, whereas those coming from a house are residential. This means that servers will be significantly rate limited and even outright blocked if they download too many videos.

The usual effect is that after a few downloads, YouTube will detect that the download is not normal traffic, and limit the speed to below what's required to watch it at normal speed. For example, a video that's 1 hour and 45 minutes long, you can expect your download to take almost 4 hours. There is no way around this, although you can try to run it with your browser cookies as explained in the Downloading premium and user-locked videos section.

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.

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.

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.

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.

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.

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.

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.

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.

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.

In all my experience with youtube-dl, I have had no problem downloading age-restricted videos, I simply downloaded them like any other video. However, in case you cannot download an age-restricted video, I recommend trying the following:

- Update youtube-dl (sometimes YouTube will change something that breaks age-restricted video downloading, and youtube-dl updates to fix it)
- Download with cookies by using the instructions in the downloading premium and user-locked videos section (this is assuming you have an account that can watch age-restricted videos)

Some people live in countries where YouTube takes a more heavy-handed approach to age-restriction, e.g. the UK. If users in these regions have issues, they can try downloading via a VPN in another country where restrictions are not so tight.

EDIT: I was correct about specific regions not being able to download age-restricted videos, notably the EU. If you live in any of these regions, you need to use a VPN or some other method to connect from a country that does not have such restrictions.

EDIT: Age restricted seems to have stopped working for everyone, unless you provide cookies for an account that is able to watch them (although I haven't tried this). This has been confirmed by me (United States), and someone else I know (United Kingdom). To check whether this affected everything, I visited a site I know that can bypass age-restricted called "nsfwyoutube.com". That site can play age-restricted videos, but they don't use youtube-dl for their backend (as far as I can tell), and they might just be using cookies from an account that is marked as 18 or older.
TL;DR: Age-restricted videos don't seem to be downloadable anymore without giving cookies.

The bottom line about downloading geo-blocked videos is that you can only download them if you can watch them. The way people usually get around blocks for those types of videos is using a VPN to connect via a country where the video is not blocked, and the same applies to youtube-dl. If a video is blocked in the United States but available in Canada, you will need to connect to a VPN in Canada and run youtube-dl while connected.

Unfortunately, while youtube-dl can get around some things (such as age-restriction this doesn't seem to be the case anymore), it cannot get around geographically blocked content by itself.

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.

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.

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.

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.

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.

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:

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.

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.

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.

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

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>

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.

This error occurs when you're trying to download a video that no longer exists.

What may have happened is the video was deleted right before you were able to download its actual audio or video contents. There's not really anything you can do, but it's worth mentioning here since it's a very confusing error to encounter.