This article has been updated on Mar 23, 2022.
Overview
There are times you may need to download a video from an online platform, whether for reference, for offline needs, or even for unique situations where you have lost access to a platform that you have videos hosted on.
youtube-dl
allows you to do just that!
youtube-dl is a command-line program to download videos from YouTube.com and a few more sites.
This quick guide will cover the installation and basic usage of youtube-dl
.
IMPORTANT NOTES:
- As of June 20, 2021, that the latest maintenance commit has been made to the repo, the core dev might be taking some time off. There is an active fork of
youtube-dl
maintained here: yt-dlp - all commands featured in this guide should work in the same way.yt-dlp
may be installed via Homebrew, viabrew install yt-dlp
. - As of November 16, 2020, youtube-dl repo has been reinstated - according to Github.
- As of October 23, 2020, the youtube-dl source code repository had been taken down from Github due to a DMCA complaint for copyright infringement, filed by the RIAA. The latest version of youtube-dl may still be downloaded and installed using Homebrew, or from the github download page - but do ensure that the content you are downloading is not under copyright protection.
Note: You don't need youtube-dl
to download videos from frame.io, just jump to the Downloading Videos from Frame.io section for a quick way to do it using your browser’s inspector.
Note: Downloading videos that are subject to copyright may be illegal, depending on the platform - especially if it's not for personal use. Some platforms don't allow download of any content altogether unless explicitly permitted by them. Youtube, as of December 2019, does not allow download of any videos from their platform: https://www.youtube.com/static?template=terms. Here are Vimeo's terms: https://vimeo.com/terms. Always ensure that the platform you are downloading videos from allows you to do so - or you may run into legal problems.
Quick Command Reference
This section acts as a quick reference for common youtube-dl
commands. Jump to the Installation section, or the Youtube-dl Usage Tips, for a more in-depth explanation of usage.
The most basic command is simply youtube-dl
, followed by the link of the video you would like to download, wrapped in quotes. youtube-dl
will attempt to download the highest quality video available and save it in the folder you are running the command from - the Home folder by default.
youtube-dl "video-url"
# set location to home directory (UNIX only) / get current directory (WIN only)
cd
# get current directory (UNIX)
pwd
# specific folder: type cd
# then drag and drop the folder into the command line
cd /path/to/folder
# parent directory
cd ..
cd
reference.youtube-dl -F "video-url"
# Take note of the format code
# for the format you wish to download
youtube-dl -f {format code, e.g: 140} -o "/Downloads/%(title)s.%(ext)s" "video-url"
youtube-dl -e "video-url"
youtube-dl -f {format code} --get-filename "video-url"
Homebrew reference
brew install youtube-dl
youtube-dl
via Homebrew.brew uninstall youtube-dl
youtube-dl
.brew List
brew -h
# or, for the manual page
man brew
Installation
youtube-dl
is a command line program and does not come in the form of an app - so you'll need to download it and run it from the command line. Launch the Terminal App in OSX or the Command Prompt on Windows to start.
You can find download details for each platform here: Download Details.
There are a number of options if you are a UNIX (OSX, Linux) user - If you are on OSX we recommend to use Homebrew - it'll make installation swift and provides easy uninstall.
Homebrew installs the stuff you need that Apple (or your Linux system) didn’t.
On Windows you may look into Chocolatey instead. (Choose Basic Install from the dropdown menu).
Homebrew
You can install Homebrew in a breeze by following the instructions on their official page: https://brew.sh.
Once installed, you can simply run brew install youtube-dl
in a new Terminal/Command Prompt window to install youtube-dl
.

For a list of installed software you can type: brew list
.
To uninstall simply type: brew uninstall youtube-dl
.
For a list of commands type: brew -h
.
For the manual page type: man brew
.
Youtube-dl Usage Tips
With youtube-dl
installed, open the Terminal app on OSX, or the Command Prompt on Windows so you can run the youtube-dl
commands.
If you are unfamiliar with the command line it essentially works by specifying a command, followed by options that define how the command is run.
The basic usage for youtube-dl
is as simple as typing youtube-dl
, then passing the full link of the video that you would like to download, in quoted form - for example:
youtube-dl "video-url"
That’s it! youtube-dl
will attempt to download the best quality version of the video and save it in the location from which you ran the command from - the default is the Home folder.
Changing Directory Basics
You can easily change the location where the video is downloaded to using the Change Directory command: cd
in the command line
cd Downloads
To specify a new location just type cd
, then drag and drop a folder into the Command Line and hit enter
.
By typing just cd
in OSX or Linux, the location will be set back to the Home folder. In Windows it will display the current location. To display the current location in OSX or Kinux, you can use the pwd
command.
By typing cd ..
the location will be set to the parent directory.
Choosing Different Formats
You can ask youtube-dl
to list the different formats available for any video using the -F
flag. A list of available formats should appear, identified by a Format Code.
youtube-dl -F "video-url"

To specify a format to download you can use the lowercase -f
flag, followed by the Format Code.
youtube-dl -f 22 "video-url"
You can also specify the best
or worse
audio or video format simply by using:
# BEST Quality (video and audio)
youtube-dl -f best "video-url"
# video only
youtube-dl -f bestvideo "video-url"
# audio only
youtube-dl -f bestaudio "video-url"
# WORST Quality (video and audio)
youtube-dl -f worst "video-url"
For more info on formats see the Format Selection section in the documentation of one of the youtube-dl
available repos.
Custom Output
When you open a new command line window and run youtube-dl
, the default output location will be the Home folder. If you change location using the cd
command, that will be the new location where the video will be downloaded to.
Note: To check what location you are in, you can type pwd
and hit enter on a UNIX system, or cd
on Windows.
To have youtube-dl
download the video to a custom folder you can use the -o
flag (for output).
youtube-dl -o "Downloads/nameOfVideo.ext" "video-url"
To specify a custom file name you can either type it manually or use the handy shortcuts provided. A shortcut is defined using this syntax: %(metadata)s
for Text and %(metadata)d
for Numbers.
youtube-dl -o "Downloads/%(title)s.%(ext)s" "video-url"
For a list of available metadata see the Output Templates section in the documentation of one of the youtube-dl
available repos.
For more info on the syntax used see: Python String Formatting.
Downloading Videos from Frame.io
Occasionally, you may receive a Frame.io link without a download button. You may use this quick hack to download it anyways.
- Open the Frameio link in your browser window.
- In the quality options of the video player, choose the resolution you want.
- Right click anywhere outside the video frame and choose Inspect Element to open the browser Inspector Window. Note: This may vary depending on which browser you are on, but every modern browser has an Inspector Window.
- Type in the search bar of the inspector:
.mp4
and hitenter
. - The inspector should jump to a
<video>
tag. Locate thesrc
attribute within that tag, double click the link specified after it and copy it. - Paste the link in the browser URL bar.
- A download prompt should appear asking you where you want to save the video. Then click
OK
to download.

src
attribute of the video tag, in the Inspector panel.
Additional Links



Update Notes
Mar 23, 2022
- Updated all
youtube-dl
official website domains fromytdl.org
->ytdl-org.github.io
Oct 7, 2021
- Updated
youtube-dl
official download link. - Updated IMPORTANT NOTES and added
yt-dlp
as an alternative solution.