ytdlp.org

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

Current section

Automation guide

Run yt-dlp in GitHub Actions

The same command that downloads fine on your laptop fails inside a GitHub Actions job with Sign in to confirm you're not a bot or HTTP Error 403. Nothing is wrong with your command. GitHub-hosted runners share a pool of datacenter IPs (Azure), and YouTube treats those IPs as suspicious. This page covers a workflow that works where it can, and the honest limit of where it can't.

First, confirm it's the IP, not your command

Run the exact command from the job on your own machine. If it works locally and only fails in the runner, the command is fine and the runner's IP is the problem:

# locally this prints the title; in a GitHub-hosted runner the same line
# often fails with "Sign in to confirm you're not a bot" or HTTP 403
yt-dlp --skip-download --print "%(title)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
# -> Me at the zoo

This is the same datacenter-IP wall you hit on a VPS or in a container — see yt-dlp works locally but not on my server. CI just hits it more often because the runner IPs are heavily shared.

A minimal workflow that does the setup right

Two things break CI jobs before the IP even matters: a stale yt-dlp and a missing JavaScript runtime. YouTube changes constantly, so install a fresh yt-dlp every run instead of pinning, and make sure a JS runtime is present (yt-dlp uses one to solve player challenges). Deno is the default it looks for:

name: fetch
on: [workflow_dispatch]

jobs:
  fetch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      # a JS runtime for yt-dlp's player challenges
      - uses: denoland/setup-deno@v2
        with:
          deno-version: v2.x

      # always install the latest release; pinned builds break fast
      - run: python3 -m pip install -U yt-dlp

      - run: yt-dlp --version
      - run: yt-dlp -o "%(title)s.%(ext)s" "$VIDEO_URL"
        env:
          VIDEO_URL: https://www.youtube.com/watch?v=jNQXAC9IVRw

You can confirm the runtime is picked up with yt-dlp -v — the debug header lists the JS runtimes it found. If it shows none, see the JavaScript runtime guide. This setup is correct — but on a flagged runner IP it can still return a bot check.

Passing cookies from a secret (and the catch)

The usual next step is to feed the job a cookies.txt exported from a signed-in browser, stored as a repository or organization secret:

- run: printf '%s' "$YT_COOKIES" > cookies.txt
  env:
    YT_COOKIES: ${{ secrets.YT_COOKIES }}
- run: yt-dlp --cookies cookies.txt "$VIDEO_URL"

Be honest with yourself about the trade-offs. Cookies tie the job to a real YouTube account, and exercising that account from a datacenter IP is exactly the pattern that gets accounts flagged or locked — use a throwaway, never your main. The cookies also expire, so a workflow that passes today quietly starts failing in a week or two. And cookies do not change the IP: a flagged runner can reject the request before cookies help at all. See how to use cookies with yt-dlp for exporting them cleanly.

If formats get skipped: a PO token provider

If the job authenticates but then skips formats or 403s on the media URLs, YouTube is asking for a GVS PO token. You can run a token provider as a service in the job rather than on a long-lived server — the setup is the same container, started as a background service. The full walkthrough is in run a yt-dlp PO token provider and the SABR/403 background is in the SABR streaming guide. A token won't fix a flagged IP either, though.

The real wall: you don't control the runner IP

Everything above can be perfect and the job still fails, because a GitHub-hosted runner picks its IP from a shared datacenter pool you have no control over. That leaves three honest options:

  • Self-hosted runner. Register your own machine as a runner so the job runs from a residential or otherwise trusted IP. This fixes the IP problem but you now maintain and secure the runner.
  • Residential proxy. Route yt-dlp through a residential proxy with --proxy. It can work, but you're paying for and babysitting proxy pools, and many are themselves flagged.
  • Move the fetch off the runner. If the job only needs the result — the file, the metadata, or a transcript — and not yt-dlp itself, call a hosted API that already runs on residential IPs, so the runner IP never touches YouTube.

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.