ytdlp.org

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

Current section

Reference guide

Choosing a YouTube player_client

When a YouTube download throws HTTP Error 403 or Requested format is not available, the advice you'll find everywhere is to "switch the player client" with --extractor-args "youtube:player_client=...". Sometimes it works. Here's what that flag actually changes, how to read which client yt-dlp is using, which clients return formats right now, and why you shouldn't bake a client name into your config and forget it.

What a "player client" is

YouTube doesn't have one API. The web page, the iOS app, the Android app, the TV interface and the embedded player each ask YouTube's servers for a video through a different internal client, and each client gets back a slightly different set of formats and stream URLs. yt-dlp mimics several of these clients and merges the results. The player_client extractor arg tells it which clients to impersonate.

This matters because YouTube rolls out restrictions (SABR-only streaming, PO-token requirements, 403s) per client, at different times. When your default set comes back broken, a client YouTube hasn't clamped down on yet may still return working URLs — that's the entire reason this flag helps.

See which clients yt-dlp is already using

Before you change anything, look at what it does by default. The verbose log names each client as it queries it:

yt-dlp -v -F "https://www.youtube.com/watch?v=jNQXAC9IVRw" 2>&1 \
  | grep -i "player API JSON"
# [youtube] jNQXAC9IVRw: Downloading tv samsung player API JSON
# [youtube] jNQXAC9IVRw: Downloading visionos player API JSON

That is the current default set on a recent build (seen on yt-dlp 2026.10.26, 2026-11-17) — it changes between releases, which is exactly why updating is the first fix, not a flag.

The syntax

Pass a comma-separated list. You can name clients outright, or start from the maintained default set and subtract one with a - prefix:

# force specific clients, in order of preference
yt-dlp --extractor-args "youtube:player_client=tv,web_safari,mweb" URL

# keep yt-dlp's default set but drop one problem client
yt-dlp --extractor-args "youtube:player_client=default,-web_embedded" URL

# list clients with -F first to see what each one returns
yt-dlp --extractor-args "youtube:player_client=mweb" -F URL

The default,-client form is usually the better move: you keep yt-dlp's current, maintained client list and only remove the one that's misbehaving, instead of pinning a single client that may be the next one to break.

Which clients work right now (and why that's a trap)

Here's the honest state of it. Running -F against the same stable public video on yt-dlp 2026.10.26 (2026-11-17, residential connection):

player_clientResult
default (no flag)Full format table
default,-web_embeddedFull format table
mwebWorks, but a reduced set (one muxed 240p format)
web_safariNo video formats found!
tvThe page needs to be reloaded

Notice that web_safari and tv— clients forum threads were recommending only weeks ago — return nothing today. This table will be wrong soon, and that's the point: never treat a specific client name as the fix. Run -F with a couple of candidates, use whichever returns the formats you need today, and expect to redo it. If you keep a client flag in a config file, add a note to re-check it.

Do these before you reach for a client flag

Switching clients is a stopgap. The durable fixes address why the default set broke in the first place:

  1. Update yt-dlp.The default client list and every client's workaround change almost every release. A build from a few weeks ago is the most common reason a client 403s. yt-dlp -U, or yt-dlp --update-to nightly if stable is still broken. See update yt-dlp.
  2. Make sure a JS runtime is present. Without one (Deno by default), yt-dlp falls back to a reduced client set — often the SABR-only ones. This bites Docker and servers most: fix "No supported JavaScript runtime" in Docker.
  3. Supply a PO token if the debug log asks for one. Some surviving format URLs now require a GVS PO token — see forcing SABR streaming & 403 and run a PO token provider on a server.

If no client works on a server

The classic trap: you find a client that works on your laptop, deploy it, and the same command still 403s on an AWS/GCP/Hetzner box — no matter which client you force. A player_client flag can't change where your request comes from, and YouTube flags datacenter IP ranges. When every client fails only on the server, it's the IP, not the client — see yt-dlp works locally but not on my server.

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.