Welcome to the yt-dlp wiki!

Contributing to the wiki

If you have any suggestions, open a PR against https://github.com/yt-dlp/yt-dlp-wiki

Do not open issues about the wiki on the main repo

FAQ - Frequently Asked Questions

Known issues

See this pinned issue for a list of some important currently known issues and the bugtracker for a full list of issues.

The yt-dlp in my Package Manager is outdated/broken

Unfortunately, there is nothing we can do if your distribution serves an outdated/broken version. You should report this to the package maintainer or your distribution in their bugtracker or support forum.

As a last resort, you can also uninstall the version installed by your package manager and follow our installation instructions to install the latest version.

Do I need any other programs?

yt-dlp works reasonably well on its own on most sites. However, some sites - most notably YouTube - serve higher quality formats as separate audio and video. You will need ffmpeg to download and merge such formats. yt-dlp also uses many other optional dependencies for additional features. See Dependencies for more information.

How do I pass cookies to yt-dlp?

Passing cookies to yt-dlp is a good way to workaround login when a particular extractor does not implement it explicitly. Another use case is working around CAPTCHA some websites require you to solve in particular cases in order to get access (e.g. YouTube, CloudFlare).

The easiest way to pass cookies is to let yt-dlp extract it from your browser (say, Chrome) using --cookies-from-browser chrome. In Linux, this searches for config in location ~/.config/google-chrome.

How do I download only new videos from a playlist?

Use download-archive feature. With this feature you should initially download the complete playlist with --download-archive /path/to/download/archive/file.txt that will record identifiers of all the videos in a special file.

yt-dlp --download-archive archive.txt "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"

Installation

You can install yt-dlp either using one of the official releases, or with your favorite package manager

If you are unfamiliar with the command line, you may use one of the many third-party GUIs available

Installing the release binary

You can simply download the correct binary file for your OS

In UNIX-like OSes (MacOS, Linux, BSD), you can also install the application into a location in your $PATH, such as ~/.local/bin:

curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o ~/.local/bin/yt-dlp\nchmod a+rx ~/.local/bin/yt-dlp  # Make executable

To update, run:

yt-dlp -U

With pip

You can install the PyPI package with:

python3 -m pip install -U "yt-dlp[default]"

Third-party package managers

Note: These packages are maintained by third-parties and may not be up-to-date. Please report any issues to the respective package maintainers

Homebrew

macOS or Linux users that are using Homebrew can also install it by:

brew install yt-dlp

pacman

Arch Linux users can install it from the official community repository:

sudo pacman -Syu yt-dlp

APT

You can download and install yt-dlp for recent Ubuntu and other related Debian-based distributions:

sudo add-apt-repository ppa:tomtomtom/yt-dlp\nsudo apt update\nsudo apt install yt-dlp

Windows Package Managers

Scoop

scoop install yt-dlp

Chocolatey

choco install yt-dlp

winget

winget install yt-dlp

Android

You can use yt-dlp on Android using Termux. Once Termux is installed, open it and run the following commands:

termux-setup-storage\npkg update && pkg upgrade\npkg install python python-pip\npip install -U "yt-dlp[default]"\npkg install ffmpeg  # OPTIONAL

YouTube Extractor

IMPORTANT
YouTube is gradually enforcing the use of a "PO Token" to be able to download videos. Due to the nature of these tokens, yt-dlp cannot generate them and they must be provided externally.

By default, yt-dlp will attempt to download videos using clients that do not currently require a PO Token. However, some formats and features may not be available without the token(s).

At this time, if you are having issues with the default clients, it is suggested to use the mweb client with a PO Token. Refer to the PO Token Guide on how to set up yt-dlp for this.

Exporting YouTube cookies

CAUTION
By using your account with yt-dlp, you run the risk of it being banned (temporarily or permanently). Be mindful with the request rate and amount of downloads you make with an account. Use it only when necessary, or consider using a throwaway account.

YouTube rotates account cookies frequently on open YouTube browser tabs as a security measure. To export cookies that will remain working with yt-dlp, you will need to export cookies in such a way that they are never rotated.

One way to do this is through a private browsing/incognito window:

1. Open a new private browsing/incognito window and log into YouTube
2. In same window and same tab from step 1, navigate to https://www.youtube.com/robots.txt
3. Export youtube.com cookies from the browser, then close the private browsing/incognito window

Common YouTube Errors

This content isn't available, try again later

This error is caused by your YouTube guest session or account exceeding the YouTube video request rate limit.

It is recommended to add a delay of around 5-10 seconds between downloads with -t sleep or with the sleep options.

With the default yt-dlp settings, the rate limit for guest sessions is ~300 videos/hour (~1000 webpage/player requests per hour). For accounts, it is ~2000 videos/hour (~4000 webpage/player requests per hour).

Plugins

How to use plugins?

Extractor Plugins

• YouTube Agegate Bypass by pukkandan
  • Bypasses YouTube age-gate using account proxy
• YouTube nsig Proxy by pukkandan
  • Uses an online solver for decrypting YouTube nsig
• YouTube nsig Deno by cute-sakura
  • Uses Deno for decrypting YouTube nsig
• YouTube PO Token Framework by coletdjnz
  • A plugin framework for yt-dlp to support fetching PO Tokens from external providers

Postprocessor Plugins

• Return Youtube Dislikes by pukkandan
  • Add dislike count from returnyoutubedislike to Youtube video metadata
• srt fixer by bindestriche
  • Fix duplicate lines in Youtube's --auto-subs when converted to srt
• FixupMtime by bradenhilton
  • Sets the mtime of all files to a given datetime value by key

Other Plugins

• yt-dlp-ChromeCookieUnlock by seproDev
  • Unlocks the cookie database for chromium based browsers
• yt-dont-lock-p by Grub4K
  • Apply a system wake lock during yt-dlp execution

Check out the yt-dlp-plugins GitHub topic for more

How do I create a plugin for yt-dlp?

A template plugin package repository is available at yt-dlp/yt-dlp-sample-plugins.

• To see how to write extractors in general, see the yt-dlp developer instructions.
• For information regarding the plugin spec, see the plugins section of the yt-dlp README.

Getting Started

1. Create a new repository based on yt-dlp/yt-dlp-sample-plugins
2. Check out the source code with: git clone git@github.com:YOUR_GITHUB_USERNAME/YOUR_REPOSITORY.git
3. Configure your IDE's run and debug configuration (optional)
4. Write your plugin code in the yt_dlp_plugins/ folder (where type is either extractor or postprocessor)
5. Configure your plugin package
6. Add the new files, commit them and push the result

Configuring your plugin package

1. Modify setup.cfg with your plugin's name and version
2. Update the installation instructions on README.md to point to this repository
3. Add yt-dlp-plugins to the repository tags for discoverability
4. Be sure to remove any of the sample extractors/post-processors

Importing extractors from other plugins

from yt_dlp_plugins.extractor.example import ExampleIE

This works regardless of where the example plugin is installed on the system, as long as yt-dlp can find it.

YouTube PO Token Guide

TIP
TL;DR recommended setup: Either use a PO Token Provider plugin, or manual extraction, to provide the mweb client with a PO Token for GVS requests.

Introduction

Proof of Origin (PO) Token is a parameter that YouTube requires to be sent with requests from some clients. Without it, requests for the affected clients' format URLs may return HTTP Error 403, or result in your account or IP address being blocked.

A PO Token is generated by an attestation provider on Web, Android and iOS platforms to attest the requests are coming from a genuine client.

Cases where a PO Token is required

There are currently two cases yt-dlp may require PO Tokens for video downloads:

• GVS: Google Video Server requests
• Player: Innertube player requests
• Subs: Subtitle requests

Current PO Token enforcement

YouTube is at present rolling out changes to enforce PO Tokens for video playback. Currently, only GVS and Subs require PO Tokens for some clients.

PO Token Provider Plugins

Manually fetching PO Tokens can be a tedious process. As an alternative, you can install a PO Token Provider plugin to handle fetching PO Tokens automatically.

Featured Plugins

• bgutil-ytdlp-pot-provider by Brainicism
  • A PO Token Provider which uses BgUtils to generate PO Tokens. Not affiliated with yt-dlp.

Guide: Providing a PO Token manually (for use with mweb client)

This section provides a basic guide on extracting PO Token(s) manually from YouTube in a web browser for use with the mweb client.

TIP
When supplying multiple PO Tokens, use the same extractor args option and comma-separate the PO Token configurations. For example:
--extractor-args "youtube:po_token=mweb.gvs+GVS_PO_TOKEN_VALUE_HERE,mweb.player+PLAYER_PO_TOKEN_VALUE_HERE"

PO Token for GVS

The PO Token used for web GVS requests is tied to your YouTube session.

No account

1. Open YouTube Music or YouTube Embedded in a browser. Make sure you are not logged in to any account!
2. Open any video
3. Open the developer console (F12), then go to the "Network" tab
4. Filter requests by googlevideo.com
5. Click the video and play for a few seconds - requests to googlevideo.com should appear
6. From the most recent googlevideo.com request, extract the pot query parameter value from the URL
7. Pass the PO Token for GVS to yt-dlp using --extractor-args "youtube:player-client=default,mweb;po_token=mweb.gvs+PO_TOKEN_VALUE_HERE"

With an account

1. Open YouTube Music in a browser, and log in with the user you are using with yt-dlp
2. Open any video
3. Follow steps 3-6 above
4. Pass the PO Token for GVS to yt-dlp using --extractor-args "youtube:player-client=default,mweb;po_token=mweb.gvs+PO_TOKEN_VALUE_HERE" with your account cookies

Forks and Related Projects

Active

• youtube-dl - The original project
• yt-dlp - This project!
• nicolaasjan/yt-dlp - Unofficial yt-dlp builds for Windows 7/XP

Inactive

• yt-dlc/youtube-dlc - yt-dlp was forked from this
• weeb-dl - Mostly Merged into yt-dlp
• haruhi-dl - Partially merged into yt-dlp

Automated releases

• yt-dlp nightly
• youtube-dl nightly