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: nonenone 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-providerLeaving 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.22With 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:4416On 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.