This article has been updated on Nov 26, 2023.


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 and a few more sites.

This quick guide will cover the installation and basic usage of youtube-dl.


  • As of November 26, 2023, the youtube-dl project has been back up and running, in parallel development with the yt-dlp alternative project. You may use either one, but if you use yt-dlp just make sure to change youtube-dl to yt-dlp in all the commands below, and they should work just fine. See Differences in Behaviour for a list of differences between youtube-dl and yt-dlp.
  • 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, via brew 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, just jump to the Downloading Videos from 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: Here are Vimeo's 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 (or yt-dlp if using that instead), 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"

# alternatively if using yt-dlp
yt-dlp "video-url"

Basic usage - saves to Home folder.

# set location to home directory (UNIX only) / get current directory (WIN only)

# get current directory (UNIX)

# specific folder: type cd
# then drag and drop the folder into the command line
cd /path/to/folder

# parent directory
cd ..

Change Directory cd reference.

youtube-dl -F "video-url"
# Take note of the format code
# for the format you wish to download

View available download formats, and their codes.

youtube-dl -f {format code, e.g: 140} -o "/Downloads/%(title)s.%(ext)s" "video-url"

Download specified video to the Downloads folder, using file name and extension.

youtube-dl -e "video-url"

Get title of video.

youtube-dl -f {format code} --get-filename "video-url"

Get filename of video, including extension.

Homebrew reference

Swap with yt-dlp if you are planning on using that alternative program.

brew install youtube-dl

Install youtube-dl via Homebrew.

brew uninstall youtube-dl

Uninstall youtube-dl.

brew List

List of software installed via Homebrew.

brew -h
# or, for the manual page
man brew

Command reference and help page.


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 MacOS 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 (MacOS, Linux) user - If you are on MacOS 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).


You can install Homebrew in a breeze by following the instructions on their official page:

Once installed, you can simply run brew install youtube-dl in a new Terminal/Command Prompt window to install youtube-dl.

Installation via Homebrew.
  • 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 MacOS, 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 (or yt-dlp if using that instead), then passing the full link of the video that you would like to download, in quoted form - for example:

youtube-dl "video-url"

# alternatively if using yt-dlp
yt-dlp "video-url"

Basic command usage.

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

Change the current location to the Downloads folder.

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 MacOS 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 MacOS or Linux, 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"

List available formats for download.

List of format codes and specs for a specified video link.

To specify a format to download you can use the lowercase -f flag, followed by the Format Code.

youtube-dl -f 22 "video-url"

Download specified format.

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"

Best and Worst quality shortcuts.

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"

Download the video in the specified format to the Downloads folder, with the specified filename.

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"

Rename the downloaded video using it's title and extension.

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

Occasionally, you may receive a link without a download button. You may use this quick hack to download it anyways.

  1. Open the Frameio link in your browser window.
  2. In the quality options of the video player, choose the resolution you want.
  3. 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.
  4. Type in the search bar of the inspector: .mp4 and hit enter.
  5. The inspector should jump to a <video> tag. Locate the src attribute within that tag, double click the link specified after it and copy it.
  6. Paste the link in the browser URL bar.
  7. A download prompt should appear asking you where you want to save the video. Then click OK to download.
Locate the src attribute of the video tag, in the Inspector panel.
Complete workflow to download videos from


Update Notes

Nov 26, 2023

  • Updated IMPORTANT NOTES on the status of youtube-dl and yt-dlp.
  • Mentioned swapping the youtube-dl Homebrew install and usage commands with yt-dlp , if using this alternative.
  • Updated Resources and included latest links.
  • Fixed broken links.

Mar 23, 2022

  • Updated all youtube-dl official website domains from ->

Oct 7, 2021

  • Updated youtube-dl official download link.
  • Updated IMPORTANT NOTES and added yt-dlp as an alternative solution.