youtube-dl Documentation

Index

Getting started

In Windows, once you have installed the Python interpreter, save the program with the .py extension and put it somewhere in the PATH. Try to follow the guide to install youtube-dl under Windows.

In Unix, download it, give it execution permission and copy it to one of the PATH directories (typically, /usr/local/bin).

After that, you should be able to call it from the command line as youtube-dl or youtube-dl.py. I will use youtube-dl in the following examples. Usage instructions are easy. Use youtube-dl followed by a video URL or identifier. Example: youtube-dl "http://www.youtube.com/watch?v=foobar". The video will be saved to the file foobar.flv in that example. As YouTube.com videos are usually in Flash Video format, their extension should be flv. In Linux and other unices, video players using a recent version of ffmpeg can play them. That includes VLC, MPlayer, etc. Those two work under Windows and other platforms, but you could also get a specific FLV player of your taste.

If you try to run the program and you receive an error message containing the keyword SyntaxError near the end, it means your Python interpreter is too old or from the 3.x branch.

More usage tips

The program is usually invoked as youtube-dl followed by options and the video URLs. Listing all the options here would make this text too long, so you can run youtube-dl --help and get a summary of them. From that point on you can start experimenting with the different options yourself. The most common ones are -t (or -l) to include the video title in the file name. Also, the -o option can specify the output file name and path. It allows special character sequences that can be used as templates to be replaced. See the "Output template" section for more details.

Some YouTube videos are served using Adobe's proprietary RTMP protocol, which imposes DRM restrictions and encrypts the connection. youtube-dl is not able to download these videos by itself. However, it will attempt to use the rtmpdump program, if it's installed in your system, to download these videos.

Frequently Asked Questions

The Frequently Asked Questions page contains answers to some common questions that pop up in my e-mail and in the issue tracker. Be sure to check it before reporting problems.

Supported sites

Proxy support

youtube-dl supports downloading videos through a proxy, by setting the http_proxy environment variable to the proxy URL, as in http://proxy_machine_name:port/.

YouTube formats

Using the -f option and other related options, you can specify the video format to be downloaded from YouTube. Instead of keeping a video format table here, I will refer you to the list of YouTube formats on Wikipedia.

Output template

The -o option allows users to indicate a template for the output file names. The basic usage is not to set any template arguments when downloading a single file, like in youtube-dl -o funny_video.flv "http://some/video". However, it may contain special sequences that will be replaced when downloading each video. The special sequences have the format %(NAME)s. To clarify, that's a percent symbol followed by a name in parenthesis, followed by a lowercase S. Allowed names are:

As you may have guessed, the default template is %(id)s.%(ext)s. When some command line options are used, it's replaced by other templates like %(title)s-%(id)s.%(ext)s. You can specify your own.

Creative Commons License
Copyright © 2006-2011 Ricardo Garcia Gonzalez