ytdlp.org

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

Current section

Server guide

YouTube transcripts that fail on a server

Your transcript script runs fine on your laptop and then returns RequestBlocked or IpBlocked the moment it runs on AWS, GCP, Render or any cloud host. This is the same datacenter-IP wall that blocks yt-dlp downloads, and the popular youtube-transcript-api library says so in its own README: "YouTube has started blocking most IPs that are known to belong to cloud providers." People hit it exactly this way — working locally, failing on AWS staging and production (reported in youtube-transcript-api issue #593, checked November 2026).

Confirm it's the IP, not your code

The current library (v1+) fetches a transcript like this:

from youtube_transcript_api import YouTubeTranscriptApi

ytt_api = YouTubeTranscriptApi()
transcript = ytt_api.fetch("jNQXAC9IVRw")   # works locally
# on a cloud host the same call raises RequestBlocked / IpBlocked

If that line succeeds on your machine and only fails once deployed, nothing is wrong with your code. The server's IP is the problem — the same reputation issue covered in yt-dlp works locally but not on my server.

The documented fix: a residential proxy

The library ships a proxy config for exactly this. Point requests through a residential proxy so they leave from a residential IP instead of the datacenter:

from youtube_transcript_api import YouTubeTranscriptApi
from youtube_transcript_api.proxies import WebshareProxyConfig

ytt_api = YouTubeTranscriptApi(
    proxy_config=WebshareProxyConfig(
        proxy_username="<proxy-username>",
        proxy_password="<proxy-password>",
    )
)
ytt_api.fetch("jNQXAC9IVRw")

Any residential proxy works through GenericProxyConfig too:

from youtube_transcript_api.proxies import GenericProxyConfig

ytt_api = YouTubeTranscriptApi(
    proxy_config=GenericProxyConfig(
        http_url="http://user:pass@my-proxy.example:port",
        https_url="https://user:pass@my-proxy.example:port",
    )
)

Why the free / datacenter proxy tier won't do it

This is the step most people get wrong. A datacenter proxy is still a datacenter IP, so it gets blocked the same way your server does. The library's own setup guide is blunt about the plan to buy: get the residential package and "make sure NOT to purchase 'Proxy Server' or 'Static Residential'!" The free tier is a datacenter proxy, so it will keep returning blocked errors. Only rotating residential IPs actually clear the wall.

That works, with real trade-offs: residential proxies are a paid, usage-metered add-on you now configure, rotate, and keep topped up, and heavily used pools get flagged over time too. You've turned a one-line fetch into an ongoing piece of infrastructure.

The other gap: videos with no captions

youtube-transcript-apionly reads caption tracks that already exist on the video. If a video has no captions — or you're pulling from a platform without them — it returns nothing, and you need actual speech-to-text on the audio instead. That's a second, separate stack to run on the server.

If you'd rather not run the proxy stack

If the job just needs the transcript and not the library itself, a hosted API that already runs on rotating residential IPs returns it from a server without you managing proxies — and can fall back to speech-to-text when a video has no captions. That's the honest case for Importly: one call takes a URL and gives you a transcript with timestamps, with the IP problem handled on their side. It's the path for servers and agent sandboxes; on your own laptop, the library above is free and fine.

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.