ytdlp.org

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

Current section

Live streams guide

How to download a YouTube live stream with yt-dlp

A live stream is not a finished file — it is an ongoing feed that yt-dlp records as it plays. That changes a few things: you decide whether to capture from now or from the start, a scheduled stream may not exist yet when you run the command, and the download has to survive the whole broadcast instead of a few seconds. The flags below cover each case, with the honest caveats at the end.

Quick answer

yt-dlp "https://www.youtube.com/watch?v=VIDEO_ID"

Point yt-dlp at a stream that is live right now and it starts recording from the current moment and keeps going until the broadcast ends (or you stop it with Ctrl-C). You do not need a special flag for a basic capture — the live URL is the same /watch?v= URL as any other video.

Capture from the beginning, not just from now

yt-dlp --live-from-start "https://www.youtube.com/watch?v=VIDEO_ID"

By default yt-dlp joins a live stream where it currently is, so anything broadcast before you ran the command is gone. --live-from-start rewinds to the start of the stream and downloads the whole thing. It only works while the stream is still live (or very recently ended), it can pull a large amount of data for a long broadcast, and it is slower than a normal download because yt-dlp has to walk every fragment from the beginning. Use --no-live-from-startto force the default "from now" behavior.

Wait for a scheduled stream

yt-dlp --wait-for-video 30-600 --live-from-start "https://www.youtube.com/watch?v=VIDEO_ID"

If the stream has not started yet, a plain command just errors out. --wait-for-video MIN-MAXtells yt-dlp to keep re-checking and begin the moment the stream goes live. The two numbers are the minimum and maximum seconds between checks (yt-dlp backs off within that range). Pair it with --live-from-start so you catch the opening, and you can leave the command running ahead of a premiere or scheduled broadcast.

Keep a playable file if the capture drops

yt-dlp --live-from-start --hls-use-mpegts -N 4 "https://www.youtube.com/watch?v=VIDEO_ID"

A live capture can run for hours, so plan for it being interrupted. --hls-use-mpegts writes the download into an MPEG-TS container, which stays playable even if the process dies mid-stream — you keep everything recorded up to the cut instead of a corrupt file. -N 4 downloads several fragments at once to keep up with a high-bitrate stream. When the stream ends cleanly you can remux to MP4 with --remux-video mp4 if you need a more portable file.

The honest caveats

Live downloads are more fragile than normal ones, and it is worth knowing why before you rely on a capture:

  • • A live stream can't be retried.For a normal video, a failed fragment is just re-requested. In a live capture there is no "back in time" — if the connection drops or gets throttled for a stretch, that part of the broadcast is simply gone.
  • • Some live formats need a PO token. YouTube increasingly gates streams behind a proof-of-origin token, and missing it shows up as missing formats or a capture that stops after a short while. If that happens, set up a token provider — see the PO token server guide.
  • • Keep yt-dlp current. YouTube player changes break live extraction faster than they break normal downloads. Run yt-dlp -U (or update your package) before a scheduled capture rather than finding out mid-stream.

Why a live capture on a server IP is doubly fragile

Running a live download from a cloud box — a VPS, a CI runner, a serverless function — stacks two problems. First, YouTube blocks or throttles traffic from datacenter IP ranges far more aggressively than home connections, so a server capture is more likely to hit a mid-stream block. Second, because a live stream can't be replayed, that block turns into a permanent gap in your recording instead of a retry. The free fix is to run captures from a clean residential IP, keep yt-dlp current, and use --live-from-start --hls-use-mpegts so an interruption still leaves a usable partial file. If your downloads keep failing specifically on a server, start with the yt-dlp blocked on a server 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.