Youtube DL Usage

Learn how to use youtube-dl

June 1, 2021

Download audio and video

This guide aims to document the usage of youtube-dl in a simplified manner. Every section explains a flag for the CLI and provides examples.


Running youtube-dl dQw4w9WgXcQ will download the video, but we want to specify the output file name and location. We can specify the output using the --output (-o) flag:

youtube-dl dQw4w9WgXcQ -o '~/Downloads/%(title)s.%(ext)s'

This will

  1. Download the video to my Downloads/ directory and
  2. Set the file name to be the <video title>.mp3.

Video format

Pass in the --format (-f) flag to choose choose the format:

  • Pass in either 3gp, aac, flv, m4a, mp3, mp4, ogg, wav, or webm
  • Pass best to select the best quality format represented by a single file with video and audio
  • Pass bestvideo to select the best quality video-only format

See "Format Selection" in the docs for more information.


Download a high quality video in the Downloads/ directory

youtube-dl dQw4w9WgXcQ -o '~/Downloads/%(title)s.%(ext)s' -f best

Download a video in the mp4 format

youtube-dl dQw4w9WgXcQ -o '~/Downloads/%(title)s.%(ext)s' -f mp4


Add the flag --extract-audio (-x).

Audio format

We can also specify a format with the flag --audio-format.

  • Pass in aac, flac, mp3, m4a, opus, vorbis, or wav
  • Or pass bestaudio to select the best audio-only format

Download a song in mp3

youtube-dl dQw4w9WgXcQ -o  '~/Downloads/%(title)s.%(ext)s' -x --audio-format mp3

Note that --format (-f) is used for video formats while --audio-format is used for audio formats.

Merging the best audio and video and more examples

Use -f bestvideo+bestaudio to download the best video-only format and the best audio-only format and merge them with ffmpeg or avonv.

youtube-dl dQw4w9WgXcQ -o '~/Downloads/%(title)s.%(ext)s' -f bestvideo+bestaudio

Note that the default format for downloading videos is -f bestvideo+bestaudio/best. If ffmpeg/avonv are available, it will download then merge the bestvideo and bestaudio. If not, it will download best.


Download the bestvideo and bestaudio but do not merge them

youtube-dl dQw4w9WgXcQ -o '~/Downloads/%(title)s.%(ext)s' -f 'bestaudio,bestvideo'

Output file name

Variables from "Output Template" can be passed in the --output to customize the output file name/location.

To use them, wrap the variable name in %( and )s, for instance -o ~/%(creator)s/%(license)s/%(title)s.%(ext)s.


I want to save the video with the name, upload date, and view count in the output file name, and keep it under a directory which is named the channel's name (/Downloads/channel-name/video-name.mkv)

youtube-dl dQw4w9WgXcQ -o '~/Downloads/%(creator)s/%(title)s-%(view_count)s.%(ext)s'

The video Rick Astley - Never Gonna Give You Up (Video)-956123176.mkv will be saved under the Rick Astley/ directory.


ERROR: AtomicParsley was not found. Please install.

Some commands from this section require AtomicParsley. To install it, go to wez/AtomicParsley and follow the instructions, or use

brew install atomicparsley

Pass the --write-thumbnail flag to download the YouTube thumbnail, and --embed-thumbnail to embed the thumbnail image.

Use --add-metadata to write metadata to the output video or audio.

For audio, pass --add-metadata and --embed-thumbdail to embed the thumbnail.


Download a video with an embedded thumbnail

youtube-dl L_jWHffIx5E -o '~/Downloads/%(title)s.%(ext)s' --write-thumbnail --embed-thumbnail

Download a song with metadata and an embedded thumbnail

youtube-dl L_jWHffIx5E -o '~/Downloads/THUMMBANIL%(title)s.%(ext)s' --add-metadata --embed-thumbnail -x

Note that the only additional flags are --add-metadata and --embed-thumbnail.


Pass --write-sub to download the subtitles as an additional file.

Additionally, pass in --embed-subs to embed the subtitles into the video file. Note that this is only supported for mp4, webm and mkv videos.

Use --sub-format with --write-sub to specify the subtitle format: ass, srt, vtt, or best.


Download a video and subtitles (if available)

youtube-dl L_jWHffIx5E -o '~/Downloads/%(title)s.%(ext)s' --write-sub

This will output two files: the video and the subtitles.

Download a video and subtitles in the srt format (of available)

youtube-dl L_jWHffIx5E -o '~/Downloads/%(title)s.%(ext)s' --write-sub --sub-format srt

If srt is not available, it will fallback to best and download another format.

Download a video with embedded subtitles (if available)

youtube-dl L_jWHffIx5E -o '~/Downloads/%(title)s.%(ext)s' --write-sub --embed-subs

This will output one file: the video with embedded subtitles.