Server guide
Running yt-dlp on AWS Lambda
Lambda looks like a natural home for "download this URL when a request comes in". It works for plenty of sites, but you hit four walls in order: a read-only filesystem, no ffmpeg, hard size and time limits, and, for YouTube, an IP range that's already flagged. The first three are packaging problems you can solve. The fourth isn't.
1. Only /tmp is writable
Your code and layers are mounted read-only. yt-dlp wants to write in three places: the output file, its .part temp files, and a cache directory (by default under $XDG_CACHE_HOME or your home directory). Point all three at /tmp, or you get Read-only file system errors:
yt-dlp -P /tmp/out --cache-dir /tmp/yt-dlp-cache "URL"
# or skip the cache entirely
yt-dlp -P /tmp/out --no-cache-dir "URL"/tmpis 512 MB by default; you can raise it up to 10,240 MB in the function's ephemeral storage setting. It also survives between warm invocations, so delete files after you upload them or a busy function eventually fills the disk.
2. Ship ffmpeg and a JS runtime: use a container image
Lambda runtimes don't include ffmpeg, and without it yt-dlp can't merge separate video and audio streams or extract audio. YouTube extraction also needs a JavaScript runtime (Deno by default) to solve player challenges. Zip deployments cap out at 250 MB unzipped including layers, which gets tight with yt-dlp, ffmpeg and Deno together. A container image (up to 10 GB) avoids the squeeze:
FROM public.ecr.aws/lambda/python:3.13
# static ffmpeg + ffprobe, and the Deno binary
COPY --from=mwader/static-ffmpeg:latest /ffmpeg /ffprobe /usr/local/bin/
COPY --from=denoland/deno:bin /deno /usr/local/bin/deno
# Deno and yt-dlp both need a writable cache location
ENV DENO_DIR=/tmp/deno XDG_CACHE_HOME=/tmp
RUN pip install --no-cache-dir -U "yt-dlp[default]"
COPY handler.py ${LAMBDA_TASK_ROOT}
CMD ["handler.handler"]Pin image tags in production instead of latest, but plan to rebuild often: yt-dlp releases frequently, and an old build inside an image is the most common reason extraction suddenly breaks. More on the runtime piece in the Docker JS runtime guide.
The handler
Use yt-dlp as a Python library rather than shelling out. The same three /tmp settings apply:
import os
import yt_dlp
def handler(event, context):
opts = {
"paths": {"home": "/tmp/out", "temp": "/tmp/out"},
"outtmpl": "%(id)s.%(ext)s",
"cachedir": "/tmp/yt-dlp-cache",
"ffmpeg_location": "/usr/local/bin/ffmpeg",
"js_runtimes": {"deno": {"path": "/usr/local/bin/deno"}},
"format": "bestaudio/best",
"quiet": True,
}
with yt_dlp.YoutubeDL(opts) as ydl:
info = ydl.extract_info(event["url"], download=True)
path = ydl.prepare_filename(info)
# upload `path` to S3 here, then clean up: /tmp survives warm starts
os.remove(path)
return {"id": info["id"], "title": info.get("title")}Don't try to return the file itself. Synchronous responses are capped at 6 MB, so write the file to S3 and return the key or a presigned URL.
3. The 15-minute ceiling
A standard Lambda invocation runs for at most 900 seconds. Short clips and audio-only downloads fit easily; long videos, big playlists and slow sources don't. Give the function more memory (CPU scales with memory, and ffmpeg merges are CPU-bound), keep one URL per invocation, and fan playlists out through a queue instead of looping inside one call. If single jobs keep brushing the limit, move them to something without one (ECS/Fargate, Batch, or a plain VM).
4. The wall packaging can't fix: AWS IPs
Your function makes requests from AWS address space. YouTube treats datacenter IPs as suspect, so a perfectly packaged Lambda often gets Sign in to confirm you're not a botor 403s on the very first request, and changing region or redeploying just gets you a different AWS IP with the same reputation. It's the same problem as yt-dlp in GitHub Actions and on any server.
The real options are the same too: route through a residential proxy (a datacenter proxy is just another flagged IP), add a PO token provider, or pass cookies from a throwaway account and accept that they expire. Each one is a moving part you now have to run next to a function that was supposed to have none. Many other sites work fine from Lambda; this wall is mostly a YouTube problem.
When Lambda stops being the right tool
If you just need a few files, run yt-dlp on your own machine where your IP is fine. If it's part of a product, the Lambda version ends up as a container you rebuild for every yt-dlp release, a residential proxy bill, and a timeout to work around. If your app only needs the file, metadata, or a transcript, a hosted media API takes the IP and maintenance problem off your side and turns the function into one HTTP call. That's the case for Importly in serverless and agent workloads.
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.