---
obj: application
os:
  - linux
repo: https://github.com/yt-dlp/yt-dlp
---
# yt-dlp
[Repo](https://github.com/yt-dlp/yt-dlp)
yt-dlp is a website media downloader. It can be used with [MPV](MPV.md).

## Usage
### Network Options
| Option      | Description                              |
| ----------- | ---------------------------------------- |
| --proxy URL | Use the specified [HTTP](../../internet/HTTP.md)/HTTPS/SOCKS proxy |

### Video Selection Options
| Option                  | Description                                                                                                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| --date DATE             | Download only videos uploaded on this date.<br>The date can be "YYYYMMDD" or in the format \[now\|today\|yesterday]\[-N\[day\|week\|month\|year]].<br>E.g. --date today-2weeks |
| --datebefore DATE       | Download only videos uploaded on or before this date                                                                                                                           |
| --dateafter DATE        | Download only videos uploaded on or after this date                                                                                                                            |
| --no-playlist           | Download only the video, if the URL refers to a video and a playlist                                                                                                           |
| --yes-playlist          | Download the playlist, if the URL refers to a video and a playlist                                                                                                             |
| --download-archive FILE | Download only videos not listed in the archive file. Record the IDs of all downloaded videos in it                                                                             |
| --max-downloads NUMBER  | Abort after downloading NUMBER files                                                                                                                                           |

### Download Options
| Option                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| -N, --concurrent-fragments N | Number of fragments of a dash/hlsnative video that should be downloaded concurrently                                                                                                                                                                                                                                                                                                                                                                                             |
| -r, --limit-rate RATE        | Maximum download rate in bytes per second, e.g. 50K or 4.2M                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -R, --retries RETRIES        | Number of retries (default is 10)                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --downloader \[PROTO:]NAME   | Name or path of the external downloader to use (optionally) prefixed by the protocols ([http](../../internet/HTTP.md), ftp, m3u8, dash, rstp, rtmp, mms) to use it for.<br>Currently supports native, aria2c, avconv, axel, [curl](../cli/network/curl.md), [ffmpeg](ffmpeg.md), [httpie](../development/HTTPie.md), wget. You can use this option multiple times to set different downloaders for different protocols.<br>E.g. --downloader aria2c --downloader "dash,m3u8:native" will use aria2c for [http](../../internet/HTTP.md)/ftp downloads, and the native downloader for dash/m3u8 downloads |

### Filesystem Options
| Option                                                             | Description                                                                                                                                    |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| -a, --batch-file FILE                                              | File containing URLs to download ("-" for stdin), one URL per line. Lines starting with "#", ";" or "]" are considered as comments and ignored |
| -o, --output [TYPES:]TEMPLATE                                      | Output filename template; see "OUTPUT TEMPLATE" for details                                                                                    |
| --restrict-filenames                                               | Restrict filenames to only [ASCII](../../files/ASCII.md) characters and avoid "&" and spaces in filenames                                                              |
| --write-description                                                | Write video description to a .description file                                                                                                 |
| --write-info-json                                                  | Write video metadata to a .info.json file                                                                                                      |
| --write-comments                                                   | Retrieve video comments to be placed in the infojson. The comments are fetched even without this option if the extraction is known to be quick |
| --cookies FILE                                                     | Netscape formatted file to read cookies from and dump cookie jar in                                                                            |
| --cookies-from-browser BROWSER\[+KEYRING]\[:PROFILE]\[::CONTAINER] | The name of the browser to load cookies from. Currently supported browsers are: [brave](../network/browsers/Brave.md), chrome, chromium, edge, [firefox](../network/browsers/Firefox.md), opera, safari, vivaldi. Optionally, the KEYRING used for decrypting Chromium cookies on [Linux](../../linux/Linux.md), the name/path of the PROFILE to load cookies from, and the CONTAINER name (if [Firefox](../network/browsers/Firefox.md)) ("none" for no container) can be given with their respective seperators. By default, all containers of the most recently accessed profile are used. Currently supported keyrings are: basictext, gnomekeyring, kwallet                                                                                                                                               | 

### Thumbnail Options
| Option                 | Description                               |
| ---------------------- | ----------------------------------------- |
| --write-thumbnail      | Write thumbnail image to disk             |
| --write-all-thumbnails | Write all thumbnail image formats to disk |

### Video Format Options
| Option                       | Description                                                                 |
| ---------------------------- | --------------------------------------------------------------------------- |
| -f, --format FORMAT          | Video format code, see "FORMAT SELECTION" for more details                  |
| -F, --list-formats           | List available formats of each video. Simulate unless --no-simulate is used |
| --merge-output-format FORMAT | Containers that may be used when merging formats, separated by "/", e.g. "mp4/[mkv](../../files/media/Matroska.md)". Ignored if no merge is required. (currently supported: avi, flv, [mkv](../../files/media/Matroska.md), mov, mp4, webm)                                                                            |

### Subtitle Options
| Option              | Description                                                                                                                                                                                                                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| --write-subs        | Write subtitle file                                                                                                                                                                                                                                                                             |
| --list-subs         | List available subtitles of each video. Simulate unless --no-simulate is used                                                                                                                                                                                                                   |
| --sub-format FORMAT | Subtitle format; accepts formats preference, e.g. "srt" or "ass/srt/best"                                                                                                                                                                                                                       |
| --sub-langs LANGS   | Languages of the subtitles to download (can be regex) or "all" separated by commas, e.g. --sub-langs "en.\*,ja". You can prefix the language code with a "-" to exclude it from the requested languages, e.g. --sub-langs all,-live_chat. Use --list-subs for a list of available language tags |

### Post-Processing Options
| Option                      | Description                                                                                                                                                            |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| -x, --extract-audio         | Convert video files to audio-only files (requires [ffmpeg](ffmpeg.md) and ffprobe)                                                                                                  |
| --audio-format FORMAT       | Format to convert the audio to when -x is used. (currently supported: best (default), aac, alac, [flac](../../files/media/audio/FLAC.md), m4a, mp3, [opus](../../files/media/audio/Opus.md), vorbis, [wav](../../files/media/audio/WAV.md))                                    |
| --remux-video FORMAT        | Remux the video into another container if necessary (currently supported: avi, flv, [mkv](../../files/media/Matroska.md), mov, mp4, webm, aac, aiff, alac, [flac](../../files/media/audio/FLAC.md), m4a, mka, mp3, ogg, [opus](../../files/media/audio/Opus.md), vorbis, [wav](../../files/media/audio/WAV.md)) |
| --embed-subs                | Embed subtitles in the video (only for mp4, webm and [mkv](../../files/media/Matroska.md) videos)                                                                                                       |
| --embed-thumbnail           | Embed thumbnail in the video as cover art                                                                                                                              |
| --embed-metadata            | Embed metadata to the video file. Also embeds chapters/infojson if present unless --no-embed-chapters/--no-embed-info-json are used                                    |
| --embed-chapters            | Add chapter markers to the video file                                                                                                                                  |
| --embed-info-json           | Embed the infojson as an attachment to [mkv](../../files/media/Matroska.md)/mka video files                                                                                                             |
| --convert-subs FORMAT       | Convert the subtitles to another format (currently supported: ass, lrc, srt, vtt)                                                                                      |
| --convert-thumbnails FORMAT | Convert the thumbnails to another format (currently supported: jpg, [png](../../files/media/image/PNG.md), webp)                                                                                         |
| --split-chapters            | Split video into multiple files based on internal chapters.                                                                                                            |

## OUTPUT TEMPLATE

The `-o` option is used to indicate a template for the output file names while `-P` option is used to specify the path each type of file should be saved to.

**tl;dr:** [navigate me to examples](https://github.com/yt-dlp/yt-dlp#output-template-examples).

The simplest usage of `-o` is not to set any template arguments when downloading a single file, like in `yt-dlp -o funny_video.flv "https://some/video"` (hard-coding file extension like this is _not_ recommended and could break some post-processing).

It may however also contain special sequences that will be replaced when downloading each video. The special sequences may be formatted according to [Python string formatting operations](https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting), e.g. `%(NAME)s` or `%(NAME)05d`. To clarify, that is a percent symbol followed by a name in parentheses, followed by formatting operations.

The field names themselves (the part inside the parenthesis) can also have some special formatting:

1.  **Object traversal**: The dictionaries and lists available in metadata can be traversed by using a dot `.` separator; e.g. `%(tags.0)s`, `%(subtitles.en.-1.ext)s`. You can do Python slicing with colon `:`; E.g. `%(id.3:7:-1)s`, `%(formats.:.format_id)s`. Curly braces `{}` can be used to build dictionaries with only specific keys; e.g. `%(formats.:.{format_id,height})#j`. An empty field name `%()s` refers to the entire infodict; e.g. `%(.{id,title})s`. Note that all the fields that become available using this method are not listed below. Use `-j` to see such fields
    
2.  **Addition**: Addition and subtraction of numeric fields can be done using `+` and `-` respectively. E.g. `%(playlist_index+10)03d`, `%(n_entries+1-playlist_index)d`
    
3.  **Date/time Formatting**: Date/time fields can be formatted according to [strftime formatting](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes) by specifying it separated from the field name using a `>`. E.g. `%(duration>%H-%M-%S)s`, `%(upload_date>%Y-%m-%d)s`, `%(epoch-3600>%H-%M-%S)s`
    
4.  **Alternatives**: Alternate fields can be specified separated with a `,`. E.g. `%(release_date>%Y,upload_date>%Y|Unknown)s`
    
5.  **Replacement**: A replacement value can be specified using a `&` separator. If the field is _not_ empty, this replacement value will be used instead of the actual field content. This is done after alternate fields are considered; thus the replacement is used if _any_ of the alternative fields is _not_ empty.
    
6.  **Default**: A literal default value can be specified for when the field is empty using a `|` separator. This overrides `--output-na-placeholder`. E.g. `%(uploader|Unknown)s`
    
7.  **More Conversions**: In addition to the normal format types `diouxXeEfFgGcrs`, yt-dlp additionally supports converting to `B` = **B**ytes, `j` = **j**son (flag `#` for pretty-printing, `+` for Unicode), `h` = HTML escaping, `l` = a comma separated **l**ist (flag `#` for `\n` newline-separated), `q` = a string **q**uoted for the terminal (flag `#` to split a list into different arguments), `D` = add **D**ecimal suffixes (e.g. 10M) (flag `#` to use 1024 as factor), and `S` = **S**anitize as filename (flag `#` for restricted)
    
8.  **Unicode normalization**: The format type `U` can be used for NFC [Unicode normalization](https://docs.python.org/3/library/unicodedata.html#unicodedata.normalize). The alternate form flag (`#`) changes the normalization to NFD and the conversion flag `+` can be used for NFKC/NFKD compatibility equivalence normalization. E.g. `%(title)+.100U` is NFKC
    

To summarize, the general syntax for a field is:

```
%(name[.keys][addition][>strf][,alternate][&replacement][|default])[flags][width][.precision][length]type
```

Additionally, you can set different output templates for the various metadata files separately from the general output template by specifying the type of file followed by the template separated by a colon `:`. The different file types supported are `subtitle`, `thumbnail`, `description`, `annotation` (deprecated), `infojson`, `link`, `pl_thumbnail`, `pl_description`, `pl_infojson`, `chapter`, `pl_video`. E.g. `-o "%(title)s.%(ext)s" -o "thumbnail:%(title)s\%(title)s.%(ext)s"` will put the thumbnails in a folder with the same name as the video. If any of the templates is empty, that type of file will not be written. E.g. `--write-thumbnail -o "thumbnail:"` will write thumbnails only for playlists and not for video.

Note: Due to post-processing (i.e. merging etc.), the actual output filename might differ. Use `--print after_move:filepath` to get the name after all post-processing is complete.

The available fields are:

-   `id` (string): Video identifier
-   `title` (string): Video title
-   `fulltitle` (string): Video title ignoring live timestamp and generic title
-   `ext` (string): Video filename extension
-   `alt_title` (string): A secondary title of the video
-   `description` (string): The description of the video
-   `display_id` (string): An alternative identifier for the video
-   `uploader` (string): Full name of the video uploader
-   `license` (string): License name the video is licensed under
-   `creator` (string): The creator of the video
-   `timestamp` (numeric): [UNIX timestamp](../../linux/UNIX%20Timestamp.md) of the moment the video became available
-   `upload_date` (string): Video upload date in UTC (YYYYMMDD)
-   `release_timestamp` (numeric): [UNIX timestamp](../../linux/UNIX%20Timestamp.md) of the moment the video was released
-   `release_date` (string): The date (YYYYMMDD) when the video was released in UTC
-   `modified_timestamp` (numeric): [UNIX timestamp](../../linux/UNIX%20Timestamp.md) of the moment the video was last modified
-   `modified_date` (string): The date (YYYYMMDD) when the video was last modified in UTC
-   `uploader_id` (string): Nickname or id of the video uploader
-   `channel` (string): Full name of the channel the video is uploaded on
-   `channel_id` (string): Id of the channel
-   `channel_follower_count` (numeric): Number of followers of the channel
-   `location` (string): Physical location where the video was filmed
-   `duration` (numeric): Length of the video in seconds
-   `duration_string` (string): Length of the video (HH:mm:ss)
-   `view_count` (numeric): How many users have watched the video on the platform
-   `concurrent_view_count` (numeric): How many users are currently watching the video on the platform.
-   `like_count` (numeric): Number of positive ratings of the video
-   `dislike_count` (numeric): Number of negative ratings of the video
-   `repost_count` (numeric): Number of reposts of the video
-   `average_rating` (numeric): Average rating give by users, the scale used depends on the webpage
-   `comment_count` (numeric): Number of comments on the video (For some extractors, comments are only downloaded at the end, and so this field cannot be used)
-   `age_limit` (numeric): Age restriction for the video (years)
-   `live_status` (string): One of "not_live", "is_live", "is_upcoming", "was_live", "post_live" (was live, but VOD is not yet processed)
-   `is_live` (boolean): Whether this video is a live stream or a fixed-length video
-   `was_live` (boolean): Whether this video was originally a live stream
-   `playable_in_embed` (string): Whether this video is allowed to play in embedded players on other sites
-   `availability` (string): Whether the video is "private", "premium_only", "subscriber_only", "needs_auth", "unlisted" or "public"
-   `start_time` (numeric): Time in seconds where the reproduction should start, as specified in the URL
-   `end_time` (numeric): Time in seconds where the reproduction should end, as specified in the URL
-   `extractor` (string): Name of the extractor
-   `extractor_key` (string): Key name of the extractor
-   `epoch` (numeric): Unix epoch of when the information extraction was completed
-   `autonumber` (numeric): Number that will be increased with each download, starting at `--autonumber-start`
-   `video_autonumber` (numeric): Number that will be increased with each video
-   `n_entries` (numeric): Total number of extracted items in the playlist
-   `playlist_id` (string): Identifier of the playlist that contains the video
-   `playlist_title` (string): Name of the playlist that contains the video
-   `playlist` (string): `playlist_id` or `playlist_title`
-   `playlist_count` (numeric): Total number of items in the playlist. May not be known if entire playlist is not extracted
-   `playlist_index` (numeric): Index of the video in the playlist padded with leading zeros according the final index
-   `playlist_autonumber` (numeric): Position of the video in the playlist download queue padded with leading zeros according to the total length of the playlist
-   `playlist_uploader` (string): Full name of the playlist uploader
-   `playlist_uploader_id` (string): Nickname or id of the playlist uploader
-   `webpage_url` (string): A URL to the video webpage which if given to yt-dlp should allow to get the same result again
-   `webpage_url_basename` (string): The basename of the webpage URL
-   `webpage_url_domain` (string): The domain of the webpage URL
-   `original_url` (string): The URL given by the user (or same as `webpage_url` for playlist entries)

All the fields in [Filtering Formats](https://github.com/yt-dlp/yt-dlp#filtering-formats) can also be used

Available for the video that belongs to some logical chapter or section:

-   `chapter` (string): Name or title of the chapter the video belongs to
-   `chapter_number` (numeric): Number of the chapter the video belongs to
-   `chapter_id` (string): Id of the chapter the video belongs to

Available for the video that is an episode of some series or programme:

-   `series` (string): Title of the series or programme the video episode belongs to
-   `season` (string): Title of the season the video episode belongs to
-   `season_number` (numeric): Number of the season the video episode belongs to
-   `season_id` (string): Id of the season the video episode belongs to
-   `episode` (string): Title of the video episode
-   `episode_number` (numeric): Number of the video episode within a season
-   `episode_id` (string): Id of the video episode

Available for the media that is a track or a part of a music album:

-   `track` (string): Title of the track
-   `track_number` (numeric): Number of the track within an album or a disc
-   `track_id` (string): Id of the track
-   `artist` (string): Artist(s) of the track
-   `genre` (string): Genre(s) of the track
-   `album` (string): Title of the album the track belongs to
-   `album_type` (string): Type of the album
-   `album_artist` (string): List of all artists appeared on the album
-   `disc_number` (numeric): Number of the disc or other physical medium the track belongs to
-   `release_year` (numeric): Year (YYYY) when the album was released

Available only when using `--download-sections` and for `chapter:` prefix when using `--split-chapters` for videos with internal chapters:

-   `section_title` (string): Title of the chapter
-   `section_number` (numeric): Number of the chapter within the file
-   `section_start` (numeric): Start time of the chapter in seconds
-   `section_end` (numeric): End time of the chapter in seconds

Available only when used in `--print`:

-   `urls` (string): The URLs of all requested formats, one in each line
-   `filename` (string): Name of the video file. Note that the [actual filename may differ](https://github.com/yt-dlp/yt-dlp#outtmpl-postprocess-note)
-   `formats_table` (table): The video format table as printed by `--list-formats`
-   `thumbnails_table` (table): The thumbnail format table as printed by `--list-thumbnails`
-   `subtitles_table` (table): The subtitle format table as printed by `--list-subs`
-   `automatic_captions_table` (table): The automatic subtitle format table as printed by `--list-subs`

Available only in `--sponsorblock-chapter-title`:

-   `start_time` (numeric): Start time of the chapter in seconds
-   `end_time` (numeric): End time of the chapter in seconds
-   `categories` (list): The [SponsorBlock categories](https://wiki.sponsor.ajay.app/w/Types#Category) the chapter belongs to
-   `category` (string): The smallest SponsorBlock category the chapter belongs to
-   `category_names` (list): Friendly names of the categories
-   `name` (string): Friendly name of the smallest category
-   `type` (string): The [SponsorBlock action type](https://wiki.sponsor.ajay.app/w/Types#Action_Type) of the chapter

Each aforementioned sequence when referenced in an output template will be replaced by the actual value corresponding to the sequence name. E.g. for `-o %(title)s-%(id)s.%(ext)s` and an mp4 video with title `yt-dlp test video` and id `BaW_jenozKc`, this will result in a `yt-dlp test video-BaW_jenozKc.mp4` file created in the current directory.

Note that some of the sequences are not guaranteed to be present since they depend on the metadata obtained by a particular extractor. Such sequences will be replaced with placeholder value provided with `--output-na-placeholder` (`NA` by default).

**Tip**: Look at the `-j` output to identify which fields are available for the particular URL

For numeric sequences you can use [numeric related formatting](https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting); e.g. `%(view_count)05d` will result in a string with view count padded with zeros up to 5 characters, like in `00042`.

Output templates can also contain arbitrary hierarchical path, e.g. `-o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s"` which will result in downloading each video in a directory corresponding to this path template. Any missing directory will be automatically created for you.

To use percent literals in an output template use `%%`. To output to stdout use `-o -`.

The current default template is `%(title)s [%(id)s].%(ext)s`.

In some cases, you don't want special characters such as 中, spaces, or &, such as when transferring the downloaded filename to a Windows system or the filename through an 8bit-unsafe channel. In these cases, add the `--restrict-filenames` flag to get a shorter title.

#### Output template examples
```shell
$ yt-dlp --print filename -o "test video.%(ext)s" BaW_jenozKc
test video.webm    # Literal name with correct extension

$ yt-dlp --print filename -o "%(title)s.%(ext)s" BaW_jenozKc
youtube-dl test video ''_ä↭𝕐.webm    # All kinds of weird characters

$ yt-dlp --print filename -o "%(title)s.%(ext)s" BaW_jenozKc --restrict-filenames
youtube-dl_test_video_.webm    # Restricted file name

# Download YouTube playlist videos in separate directory indexed by video order in a playlist
$ yt-dlp -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"

# Download YouTube playlist videos in separate directories according to their uploaded year
$ yt-dlp -o "%(upload_date>%Y)s/%(title)s.%(ext)s" "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"

# Prefix playlist index with " - " separator, but only if it is available
$ yt-dlp -o '%(playlist_index|)s%(playlist_index& - |)s%(title)s.%(ext)s' BaW_jenozKc "https://www.youtube.com/user/TheLinuxFoundation/playlists"

# Download all playlists of YouTube channel/user keeping each playlist in separate directory:
$ yt-dlp -o "%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "https://www.youtube.com/user/TheLinuxFoundation/playlists"

# Download Udemy course keeping each chapter in separate directory under MyVideos directory in your home
$ yt-dlp -u user -p password -P "~/MyVideos" -o "%(playlist)s/%(chapter_number)s - %(chapter)s/%(title)s.%(ext)s" "https://www.udemy.com/java-tutorial"

# Download entire series season keeping each series and each season in separate directory under C:/MyVideos
$ yt-dlp -P "C:/MyVideos" -o "%(series)s/%(season_number)s - %(season)s/%(episode_number)s - %(episode)s.%(ext)s" "https://videomore.ru/kino_v_detalayah/5_sezon/367617"

# Download video as "C:\MyVideos\uploader\title.ext", subtitles as "C:\MyVideos\subs\uploader\title.ext"
# and put all temporary files in "C:\MyVideos\tmp"
$ yt-dlp -P "C:/MyVideos" -P "temp:tmp" -P "subtitle:subs" -o "%(uploader)s/%(title)s.%(ext)s" BaW_jenoz --write-subs

# Download video as "C:\MyVideos\uploader\title.ext" and subtitles as "C:\MyVideos\uploader\subs\title.ext"
$ yt-dlp -P "C:/MyVideos" -o "%(uploader)s/%(title)s.%(ext)s" -o "subtitle:%(uploader)s/subs/%(title)s.%(ext)s" BaW_jenozKc --write-subs

# Stream the video being downloaded to stdout
$ yt-dlp -o - BaW_jenozKc
```