friedrichrehren/yt-dlp repository overview

⁠Included Tools

⁠Published Images

The latest image follows the newest upstream yt-dlp release. Versioned image tags match upstream release tags such as 2026.03.17. A separate nightly tag is rebuilt from the upstream nightly channel on each scheduled run and replaces the previous nightly image.

⁠What This Project Does

This project watches upstream yt-dlp releases and republishes them as Docker images.

The repository automation:

1. checks yt-dlp/yt-dlp once an hour
2. builds a new image when the latest upstream release is missing on GHCR or Docker Hub (only the registry that lacks it is pushed to)
3. smoke-tests every image (yt-dlp, ffmpeg, deno) before it is pushed
4. rebuilds the nightly image once per day from the upstream nightly channel and replaces the previous nightly tag
5. keeps its scheduled workflows enabled – GitHub would otherwise disable them after 60 days without commits

The container itself is intentionally simple. Its entrypoint is yt-dlp, so the image behaves like a containerized yt-dlp CLI with the upstream recommended runtime pieces already present.

⁠Quick Start

Both registries publish the same tags and multi-arch images. Choose the one you prefer:

⁠GHCR

Image: ghcr.io/friedrichrehren/yt-dlp

Pull the image from GHCR:

docker pull ghcr.io/friedrichrehren/yt-dlp:latest

Or use the upstream nightly channel tag:

docker pull ghcr.io/friedrichrehren/yt-dlp:nightly

Check the installed version:

docker run --rm ghcr.io/friedrichrehren/yt-dlp:latest --version

⁠Docker Hub

Image: friedrichrehren/yt-dlp

Pull the image from Docker Hub:

docker pull friedrichrehren/yt-dlp:latest

Or use the upstream nightly channel tag:

docker pull friedrichrehren/yt-dlp:nightly

Check the installed version:

docker run --rm friedrichrehren/yt-dlp:latest --version

⁠How To Use The Image

Because the container entrypoint is already yt-dlp, everything after the image name is passed directly to yt-dlp.

⁠GHCR

Image: ghcr.io/friedrichrehren/yt-dlp

Download into a host directory:

docker run --rm \
  -v /path/to/downloads:/downloads \
  ghcr.io/friedrichrehren/yt-dlp:latest \
  https://www.youtube.com/watch?v=example

Use a pinned yt-dlp version:

docker run --rm \
  -v /path/to/downloads:/downloads \
  ghcr.io/friedrichrehren/yt-dlp:2026.03.17 \
  --version

Merge audio and video with the bundled ffmpeg:

docker run --rm \
  -v /path/to/downloads:/downloads \
  ghcr.io/friedrichrehren/yt-dlp:latest \
  --format "bv*+ba/b" \
  --merge-output-format mp4 \
  https://www.youtube.com/watch?v=example

Extract audio:

docker run --rm \
  -v /path/to/downloads:/downloads \
  ghcr.io/friedrichrehren/yt-dlp:latest \
  --extract-audio \
  --audio-format mp3 \
  https://www.youtube.com/watch?v=example

⁠Docker Hub

Image: friedrichrehren/yt-dlp

Download into a host directory:

docker run --rm \
  -v /path/to/downloads:/downloads \
  friedrichrehren/yt-dlp:latest \
  https://www.youtube.com/watch?v=example

Use a pinned yt-dlp version:

docker run --rm \
  -v /path/to/downloads:/downloads \
  friedrichrehren/yt-dlp:2026.03.17 \
  --version

Merge audio and video with the bundled ffmpeg:

docker run --rm \
  -v /path/to/downloads:/downloads \
  friedrichrehren/yt-dlp:latest \
  --format "bv*+ba/b" \
  --merge-output-format mp4 \
  https://www.youtube.com/watch?v=example

Extract audio:

docker run --rm \
  -v /path/to/downloads:/downloads \
  friedrichrehren/yt-dlp:latest \
  --extract-audio \
  --audio-format mp3 \
  https://www.youtube.com/watch?v=example

⁠Build Locally

Build the latest upstream yt-dlp release:

docker build -t yt-dlp:latest .

Build a specific upstream release:

docker build \
  --build-arg YTDLP_VERSION=2026.03.17 \
  -t yt-dlp:2026.03.17 .

⁠Build Arguments

• YTDLP_VERSION: upstream yt-dlp release tag to download. Defaults to latest. Set it to nightly to download the upstream nightly build channel instead of a tagged stable release.
• PYTHON_IMAGE: base image to build from. Defaults to python:3.14-slim.
• DENO_VERSION: Deno release to install for JavaScript execution. Defaults to 2.6.4.

Example with an explicit base image:

docker build \
  --build-arg PYTHON_IMAGE=python:3.14-slim \
  --build-arg YTDLP_VERSION=latest \
  -t yt-dlp:custom .

⁠Image Behavior

The image:

• installs ffmpeg from Debian packages
• installs ffprobe from the same Debian package set
• installs AtomicParsley
• installs deno for JavaScript execution
• installs the Python package curl_cffi
• downloads the upstream yt-dlp binary during build
• runs as UID 65532
• uses /downloads as the working directory

That means mounted download paths should normally target /downloads.

⁠Repository Setup

⁠Workflows

⁠Secrets