dotwee/jellyfin-yt-dlp repository overview

⁠dotwee/jellyfin-yt-dlp⁠

⁠Features

• Based on official jellyfin/jellyfin⁠ images (release & unstable)
• Latest yt-dlp⁠ preinstalled
• ffmpeg always present (required for yt-dlp)
• Pre-configured yt-dlp with optimized settings for Jellyfin
• Automatic validation of dependencies at container start
• Non-root user for security
• Multi-arch: linux/amd64, linux/arm64
• Healthcheck for robust orchestration
• CI/CD: Automated builds and publishing on new releases

⁠Usage

⁠Pull from Docker Hub

docker pull dotwee/jellyfin-yt-dlp:latest
# or for unstable
# docker pull dotwee/jellyfin-yt-dlp:unstable

⁠Run with Docker

docker run -d \
  --name jellyfin \
  -p 8096:8096 \
  -v /path/to/config:/config \
  -v /path/to/media:/media \
  dotwee/jellyfin-yt-dlp:latest

⁠Environment Variables

All standard Jellyfin environment variables are supported. See Jellyfin docs⁠.

⁠yt-dlp Configuration

This image comes with a pre-configured yt-dlp setup optimized for Jellyfin usage.

⁠Default Configuration

The container includes a default configuration file at /etc/yt-dlp.conf with the following settings:

• FFmpeg Path: Correctly configured to use /usr/lib/jellyfin-ffmpeg/ffmpeg
• Output Format: Organized by uploader and title: %(uploader)s/%(title)s.%(ext)s
• Quality: Best quality up to 1080p for compatibility
• Container: Prefers MP4 for better Jellyfin compatibility
• Subtitles: Embeds available subtitles (English variants)
• Thumbnails: Embeds thumbnails as cover art
• Metadata: Writes info JSON files
• Rate Limiting: 5MB/s to be respectful to servers
• Retries: 3 attempts on failures

⁠Custom Configuration

⁠User-Specific Configuration

To override the default configuration, mount your custom config file to one of these locations:

1. User config directory (recommended):

   # Create your custom config file
   mkdir -p /path/to/config/.config/yt-dlp
   echo "--format best[height<=720]" > /path/to/config/.config/yt-dlp/config
   
   # Mount it in the container
   docker run -d \
     --name jellyfin \
     -v /path/to/config:/config \
     dotwee/jellyfin-yt-dlp:latest
   

   Copy

2. System-wide override:

   # Mount your custom config file
   docker run -d \
     --name jellyfin \
     -v /path/to/your/yt-dlp.conf:/etc/yt-dlp.conf:ro \
     dotwee/jellyfin-yt-dlp:latest
   

   Copy

⁠Configuration File Locations (Priority Order)

yt-dlp searches for configuration files in this order:

1. /config/.config/yt-dlp/config (user-specific, recommended for customization)
2. /etc/yt-dlp.conf (system-wide default)
3. Command-line arguments (highest priority)

⁠Example Custom Configuration

# Example: /path/to/config/.config/yt-dlp/config

# Use Jellyfin's ffmpeg (required)
--ffmpeg-location /usr/lib/jellyfin-ffmpeg/ffmpeg

# Custom output template
--output "/media/downloads/%(uploader)s - %(title)s.%(ext)s"

# Lower quality for storage savings
--format "best[height<=720]"

# Skip subtitles
--no-embed-subs

# Custom rate limit
--limit-rate 10M

# Archive to prevent re-downloading
--download-archive /config/yt-dlp-archive.txt

⁠Important Notes

• FFmpeg Path: Always keep --ffmpeg-location /usr/lib/jellyfin-ffmpeg/ffmpeg in your config
• Output Paths: Use paths within mounted volumes (e.g., /media/, /config/)
• Permissions: Ensure the container can write to your specified output directories
• Archive Files: Store archive files in /config/ to persist across container restarts

⁠Building the Image

⁠Build Arguments

• JELLYFIN_VERSION (default: latest): Jellyfin version or unstable for nightly

⁠Example: Build for latest release

docker build --build-arg JELLYFIN_VERSION=latest -t jellyfin-yt-dlp:latest .

⁠Example: Build for unstable

docker build --build-arg JELLYFIN_VERSION=unstable -t jellyfin-yt-dlp:unstable .

⁠Healthcheck & Validation

• The container validates yt-dlp and ffmpeg on startup and for healthchecks.
• If either is missing or broken, the container will exit with an error.

⁠Advanced: CI/CD & Auto-Publishing

This repository is set up for automated builds and publishing via GitHub Actions:

• On every new Jellyfin or yt-dlp release, a new image is built and pushed to Docker Hub and GHCR.
• See .github/workflows/docker-image-ci.yml⁠ for details.

⁠Troubleshooting

⁠Common Issues

• yt-dlp or ffmpeg not found?
  • The container will not start if dependencies are missing. Check logs for errors.
• Permissions issues?
  • The container runs as a non-root user (jellyfinuser). Ensure your mounted volumes are accessible.
• FinTube not working?
  • Ensure you are using the correct plugin version and that yt-dlp is up to date.

⁠yt-dlp Specific Issues

• Downloads failing?
  • Check your yt-dlp configuration file for correct paths and permissions
  • Ensure the ffmpeg path is set to /usr/lib/jellyfin-ffmpeg/ffmpeg
• Custom config not loading?
  • Verify the config file is mounted to /config/.config/yt-dlp/config
  • Check file permissions (should be readable by the container user)
• Output files not appearing?
  • Ensure output paths in your config point to mounted volumes
  • Check that the container has write permissions to the output directory

⁠Debug Commands

# Check yt-dlp version and config
docker exec jellyfin yt-dlp --version

# Test yt-dlp with a simple video
docker exec jellyfin yt-dlp --dry-run "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# Check current configuration
docker exec jellyfin yt-dlp --help | head -20

⁠Credits

• Jellyfin⁠
• yt-dlp⁠
• FinTube⁠

⁠License

Copyright (c) 2025 Lukas 'dotWee' Wolfsteiner [email protected]⁠

Licensed under the do what the fuck you want to⁠ public license