ytdlp.org

Practical yt-dlp docs: install, commands, fixes, cookies, and workflows.

Current section

Server guide

Run a PO token provider next to yt-dlp

YouTube now expects a GVS PO token on many of the format URLs yt-dlp hands back — without one you get skipped formats and HTTP Error 403. On a laptop you can lean on browser cookies, but on a headless server the clean answer is to run a token provider as a sidecar so yt-dlp generates tokens itself. This is the bgutil-ytdlp-pot-provider setup, which is maintained by a yt-dlp maintainer.

First, confirm you actually have no provider

A default yt-dlp install ships no PO token provider. Check with a verbose simulate:

yt-dlp -v --simulate "https://www.youtube.com/watch?v=jNQXAC9IVRw" 2>&1 | grep -i pot
# [debug] [youtube] [pot] PO Token Providers: none

none is the thing to fix. The provider has two parts: a small HTTP service that mints tokens, and a yt-dlp plugin that calls it.

Step 1: run the provider as a container

The provider runs an HTTP server on port 4416. Bind it to localhost — it's unauthenticated, so you don't want it reachable from the outside:

docker run --name bgutil-provider -d --init \
  -p 127.0.0.1:4416:4416 brainicism/bgutil-ytdlp-pot-provider

Leaving off the 127.0.0.1: prefix would expose the server on every interface — don't.

Step 2: install the yt-dlp plugin

Install it into the same environment as yt-dlp. You need yt-dlp 2025.05.22 or newer:

python3 -m pip install -U bgutil-ytdlp-pot-provider
yt-dlp --version   # confirm >= 2025.05.22

With the provider on the default http://127.0.0.1:4416, yt-dlp finds it automatically — no extra flags. If you run it on a different host or port, point the plugin at it:

yt-dlp --extractor-args "youtubepot-bgutilhttp:base_url=http://127.0.0.1:8080" "URL"

Step 3: verify a token is actually generated

Re-run the verbose simulate. You want to see the provider listed and a line showing a token being minted:

yt-dlp -v "https://www.youtube.com/watch?v=jNQXAC9IVRw" 2>&1 | grep -i pot
# [debug] [youtube] [pot] PO Token Providers: bgutil:http-2.0.2 (external)
# [youtube] [pot:bgutil:http] Generating a gvs PO Token for mweb client...

If the provider shows up but you never see a Generating a gvs PO Token line, nudge the client selection, e.g. --extractor-args "youtube:player-client=mweb,tv,web_safari".

Keep it alongside yt-dlp in compose

If yt-dlp already runs in a container, add the provider as a second service so they start and stop together:

services:
  bgutil-provider:
    image: brainicism/bgutil-ytdlp-pot-provider
    init: true
    restart: unless-stopped

  ytdlp:
    build: .            # your yt-dlp image (with a JS runtime)
    depends_on: [bgutil-provider]
    environment:
      # provider is reachable by service name on the compose network
      - YTDLP_POT_BASE_URL=http://bgutil-provider:4416

On the compose network the two containers reach each other by service name, so point the plugin at http://bgutil-provider:4416 with the same youtubepot-bgutilhttp:base_url arg. You still need a JavaScript runtime in the yt-dlp image — see the Docker JS runtime guide.

The honest limit: a token won't fix your IP

The provider's own docs say it plainly: a PO token does not guarantee bypassing 403 errors or bot checks, and it won't get past IP-based restrictions. If your server sits on a datacenter IP that YouTube has flagged, you can have a perfectly working token provider and still get 403s or "sign in to confirm you're not a bot." The token solves the GVS requirement; the IP is a separate wall. For that, see yt-dlp works locally but not on my server and the SABR/403 guide.

Servers & agents

Works on your laptop but not on the server?

Paste a link to see what a hosted API returns from a clean residential IP — no cookies, proxies, or runtime to maintain on the box.

Straightforward yt-dlp help for installs, commands, fixes, cookies, and repeatable workflows.

ytdlp.org is an independent, community-maintained documentation site. It is not affiliated with the yt-dlp project — the official source code lives at github.com/yt-dlp/yt-dlp.