haven/yt-dlp repository overview

⁠haven/yt-dlp

Containerized yt-dlp⁠ with aria2 acceleration and an opinionated wrapper script at /opt/scripts/yt-dlp.sh⁠.

Defaults favour playlist/file mode using /media/channel_list.txt and run in foreground for logs.

⁠Quick start (playlist mode – default)

1. Create a host directory (i.e. /path/on/host) and a channel_list.txt file with one URL per line:

   https://www.youtube.com/@royalsociety/videos
   https://www.youtube.com/@GreatBigStory/videos
   

   Copy

2. Generate cookies.txt (on a laptop or desktop with a browser logged into youtube):

   yt-dlp --cookies-from-browser brave --cookies cookies.txt
   

   Copy

   Copy cookies.txt to your '/path/on/host' folder.

3. Run the container and mount your directory to /media:

   docker run --rm -it \
     -v /path/on/host:/media \
     haven/yt-dlp:latest
   

   Copy

This will run /opt/scripts/yt-dlp.sh --foreground by default and read URLs from /media/channel_list.txt. By default it downloads items from the last 7 days; see env vars below to change this.

If you get 403 returns when downloading you likely need to re-generate the cookies.txt and try again.

⁠One-shot mode (single URL)

Pass a URL via --input-source and enable --oneshot (downloads all unless you also set a date filter):

docker run --rm -it \
  -v /path/on/host:/media \
  haven/yt-dlp:latest \
  --oneshot --input-source "https://www.youtube.com/@royalsociety/videos"

⁠Environment variables (overrides)

All key runtime settings can be overridden via Docker env vars or CLI parameters:

Examples:

docker run --rm -it \
  -v /srv/youtube:/media \
  -e YTDLP_DAYS=14 \
  -e YTDLP_CODEC=vp9 \
  -e YTDLP_SUBTITLE_LANGS="en,es" \
  haven/yt-dlp:latest

AV1 example (CPU encode, WebM output):

docker run --rm -it \
  -v /srv/youtube:/media \
  -e YTDLP_CODEC=av1 \
  haven/yt-dlp:latest

⁠Choosing a codec (MP4/H.264 vs VP9 vs AV1)

You can select the preferred codec via --codec {mp4|vp9|av1} or -e YTDLP_CODEC=.... The script will fall back smartly when the exact choice is not available.

Notes:

• The image enables software H.264 encoding (x264) and AV1 encoding (SVT-AV1). VP9 is available (libvpx) if needed, but default output is MP4/H.264 unless --codec is set.
• Hardware acceleration is not enabled in this image; all encoding/decoding is CPU-only.
• YouTube doesn’t serve MP3; typical audio is AAC (MP4) or Opus (WebM). No MP3 encoder is included.

⁠Volumes and permissions

• The image declares VOLUME ["/media"]. Mount your host directory there.

• Container runs as user 1000:1000 by default. Ensure the mounted host directory is writable by this UID/GID, or override at runtime:

  docker run --rm -it \
    --user $(id -u):$(id -g) \
    -v /path/on/host:/media \
    haven/yt-dlp:latest
  

  Copy

⁠Volumes and permissions

• The image declares VOLUME ["/media"]. Mount your host directory there.

• Container runs as user 1000:1000 by default. Ensure the mounted host directory is writable by this UID/GID, or override at runtime:

  docker run --rm -it \
    --user $(id -u):$(id -g) \
    -v /path/on/host:/media \
    haven/yt-dlp:latest
  

  Copy

⁠Cookies support (optional)

If a cookies.txt file exists at ${YTDLP_DOWNLOAD_DIR}/cookies.txt (default /media/cookies.txt), it will be used automatically. This is useful for authenticated or age-restricted content.

⁠Output layout

Files are written under ${YTDLP_DOWNLOAD_DIR} into folders by uploader and playlist, with metadata, description, info JSON, and embedded thumbnails/subtitles by default.

⁠Timezone

• Date filtering (via YTDLP_DAYS) uses the container timezone. Set it explicitly if you need a specific zone:

  docker run --rm -it \
    -e TZ=Europe/London \
    -v /path/on/host:/media \
    haven/yt-dlp:latest
  

  Copy

⁠Notes

• By default the script filters to the last YTDLP_DAYS days in playlist mode. Set a different value with -e YTDLP_DAYS=30 or disable date filtering by using --oneshot for direct URLs.
• The image includes a healthcheck that validates the presence of /opt/scripts/yt-dlp.sh, yt-dlp on PATH, and writa bility of /media.

Last Build⁠