🎬 HomeTube is a simple web UI for downloading single videos and playlists from the internet with the highest quality available and moving them to specific local locations automatically managed and integrated by media server such as Plex or Jellyfin.

A simple friendly solution for easily integrating preferred videos from Youtube and others platforms to local media server:

• 🚫 Ad-Free Content: Block natively all videos' ads and sponsors
• 🏆 Best Quality Control: Advanced best videos quality download strategy or manual override
• 🎬 Media Server Ready: Download best quality videos with explicit name and location directly in your HomeLab media server structure and get automatic watch experience on Plex, Jellyfin, Emby or even on your PC
• 📋 Intelligent Playlist Sync: Download and synchronize playlists with resilient tracking - local library stays perfectly in sync with source
• 📱 Network Access: Web interface videos download accessible from any device on your network
• 🎯 One-Click Downloads: Paste URL → Get perfectly organized video
• 🔐 Cookies Authentication: Essential for reliable downloads - unlocks restricted content and prevents signature errors
• 🎬 Advanced Processing: Cut clips, embed subtitles, convert formats
• ⚙️ Advanced Configurations: Organized advanced options including any custom yt-dlp arguments (proxy, max-filesize, etc.)
• 🎥 Video Sources: YouTube, Reddit, Vimeo, Dailymotion, TikTok, Twitch, Facebook, Instagram, etc. See complete list (1800+)

Automatic integration with self-hosted setup:

• 🐳 Docker Ready: One-command deployment with Docker Compose
• 🎬 Media Server Integration: Direct integration with media server thanks to well named video files automatically moved to chosen locations watched by media server such as Plex, Jellyfin, or Emby.
• 🆕 Create new folder from the UI: Create organized new folder structures when necessary from the "🆕 Create New Folder" option at the bottom of the "Destination folder" field listing menu (e.g., Tech/Python/Advanced)
• 📱 Network Access: Web interface accessible from any device on your network
• 🔐 Secure: No cloud dependencies, everything runs locally
• ⚙️ Configurable: Extensive customization through environment variables

Setup your HomeLab integration.

Automatically skip sponsors, ads, and promotional content with built-in SponsorBlock support. Just download your video and sponsors segments are automatically detected and marked.

• ✅ Auto-detection: Sponsors segments automatically identified
• ✅ Manage sponsors to block: Sponsors segments to block or mark can be managed in the UI
• ✅ Community-driven: Powered by SponsorBlock's crowd-sourced database
• ✅ Zero configuration: Works out of the box for YouTube videos

Learn more about SponsorBlock features.

Cookies authentication should be setup for optimal video downloading experience and to avoid common download failures.

Even for public YouTube videos, cookies are increasingly necessary because of modern protections.
They ensure higher quality, reliability, and access to all formats:

• 🏆 Access the best quality (AV1/Opus, high-res video, premium audio)
• 🔓 Unlock restricted content (age-gated, member-only, region-locked)
• 🔐 Handle encrypted signatures (n-sig) required for many video/audio streams
• 🛡️ Bypass anti-bot measures that block automated downloaders
• 📺 Ensure stream availability (audio/video may be signature-protected even for public videos)
• ⚡ Improve reliability (fewer "format unavailable" or extraction errors)
• 🎵 Get high-quality audio tracks (Opus, AAC) without failures
• 🚀 Reduce throttling for faster, more stable downloads

👉 In short: cookies are not just for private content — they’re the key to consistent, best-quality downloads.

We can use Browser cookies if on a machine sharing a browser, otherwise Cookies File in HomeLab setup.

More details about Cookies authentication setup.

Transform your downloads with powerful built-in video processing tools:

• 🎬 Clip Extraction: Cut specific segments from videos with precision timing
• 📝 Subtitle Embedding: Automatically embed subtitles in multiple languages
• 🔄 Format Conversion: Convert between video formats (MP4, MKV, WebM, etc.)
• 🎵 Audio Extraction: Extract audio-only versions in high quality
• 📱 Mobile Optimization: Optimize videos for mobile devices

Explore all processing options.

Custom yt-dlp arguments support offers full flexibility for advanced users to tailor downloads to specific needs.

• 📱 Network configuration: --proxy http://proxy.company.com:8080 --retries 5
• 📂 File size limits: --max-filesize 500M --min-filesize 100M
• 📋 Enhanced metadata: --write-info-json --write-description --write-thumbnail
• 🛜 Bandwidth control: --limit-rate 1M --fragment-retries 10
• ➕ More options: yt-dlp --options variable

Custom yt-dlp arguments can be added directly from the UI or set by default for any download with the YTDLP_CUSTOM_ARGS environment variable.

🔀 Smart Conflict Resolution: HomeTube automatically detects and resolves conflicts between base settings and custom arguments, giving priority to your custom preferences while maintaining system stability.

HomeTube uses intelligent quality detection that analyzes each video and automatically selects the best available formats with a simple 2-profile strategy:

🔍 How It Works:

• 📊 Real-time Analysis → Detects all available video formats and codecs
• 🏆 Smart Ranking → Prioritizes modern codecs (AV1 > VP9 > H.264) and audio quality (Opus > AAC)
• 🎯 Optimal Selection → Generates up to 2 best profiles from actual available formats
• 🔄 Intelligent Fallback → Tries best quality first, then second-best if needed

Quality Profiles Generated:

1. 🥇 Best Available → Highest resolution with most modern codec (e.g., 4K AV1 + Opus)
2. 🥈 Fallback Option → Next best combination (e.g., 4K VP9 + Opus)

Download Strategies:

• 🔄 Auto Best (Default) → Tries up to 2 optimal profiles automatically until success
• 🏆 Best Only → Only attempts highest quality, no fallback (stops if unavailable)
• 🎯 Choose Profile → Manually select from detected optimal profiles
• 📋 Choose Format → Advanced: select specific format IDs from all available formats

🚀 Benefits:

• ✅ Always gets the best quality actually available for each video
• ✅ No generic fallbacks - uses real format analysis
• ✅ Fast downloads with minimal retries (max 2 attempts)
• ✅ Supports all modern codecs: AV1, VP9, H.264, Opus, AAC

👉 Full details on quality detection & strategies

Intelligent download system that adapts to your needs:

• 📁 Auto-Organization: Videos organized by channel/creator automatically
• ⚡ Resume Support: Interrupted downloads automatically resume
• 💾 Storage Optimization: Duplicate detection and space management

Learn more about download features.

Powerful playlist synchronization with resilient tracking and perfect source fidelity:

🔄 Smart Synchronization:

• 📡 Source of Truth: YouTube playlist is always the reference - local library stays perfectly synchronized
• 🔄 Auto-Refresh: Playlist metadata automatically refreshed on each load for accurate status
• 📊 Instant Status: See exactly which videos are downloaded, pending, or new at a glance
• 🎯 Incremental Downloads: Only download new videos - existing ones are preserved and tracked

📁 Resilient Video Tracking:

• 🆔 ID-Based Tracking: Videos tracked by unique ID - survives title changes on YouTube
• 📝 Pattern-Based Naming: Flexible filename patterns with placeholders ({idx}, {title}, {channel}, etc.)
• 🔄 Smart Rename Detection: Finds renamed files in destination folder automatically
• 📂 Index Preservation: Maintains playlist order even when videos are reordered upstream

🛡️ Robust Change Detection:

• ➕ New Videos: Automatically detected and queued for download
• 🔢 Reordering: Detect and apply index changes with smart renaming
• 📂 Relocation: Move entire playlist to new folder while preserving files
• 📦 Archive Mode: Removed videos can be archived instead of deleted
• 🗑️ Clean Removal: Optional deletion of videos removed from source playlist

🎨 Customizable Title Patterns:

{idx} - {pretty(title)}.{ext}           → 01 - My Video Title.mkv
{pretty(title)} - {channel}.{ext}       → My Video - Creator Name.mkv  
{i:03d} - {slug(title)} [{id}].{ext}    → 001 - my-video-title [abc123].mkv

Supported placeholders:

• {idx} - Smart zero-padded index (01, 02... or 001, 002... based on total)
• {title} / {pretty(title)} / {slug(title)} - Video title variants
• {channel} / {pretty(channel)} / {slug(channel)} - Channel name variants
• {id} - Video ID • {ext} - File extension

📈 Progress Tracking:

• Real-time download progress with visual indicators
• Detailed sync plan preview before applying changes
• Full logging of all operations for transparency

Set PLAYLIST_KEEP_OLD_VIDEOS=true (or enable Keep videos removed from playlist in the UI) to move removed entries into an Archives/ folder instead of deleting them.

1800+ supported platforms - way beyond just YouTube:

• 📺 Major Platforms: YouTube, Twitch, Vimeo, Dailymotion, TikTok
• 🎭 Social Media: Instagram, Facebook, Twitter, Reddit
• 🎓 Educational: Coursera, Khan Academy, edX
• 🏢 Professional: LinkedIn Learning, Udemy, Skillshare
• 📺 Streaming: Netflix previews, Hulu trailers, Disney+ clips

See complete platform list.

📋 HomeTube uses environment variables for all configurations: videos download paths, temporary download folder, authentication, languages, quality profiles, and more.

Depending of the setup, Docker, Docker compose, Portainer, local run, environment variables can be passed to the application in different ways.

.env file from .env.sample can be practical for rapid setup:

# 1. Clone repository (if not already done)
git clone https://github.com/EgalitarianMonkey/hometube.git
cd hometube

# 2. Create your own configuration file from the sample
cp .env.sample .env

With Docker, environment variables can be passed either with -e VARIABLE= arguments or --env-file .env.

-e VARIABLE=

docker run -p 8501:8501 \
  -e TZ=America/New_York \
  -e VIDEOS_FOLDER=/data/videos \
  -e TMP_DOWNLOAD_FOLDER=/data/tmp \
  -e YOUTUBE_COOKIES_FILE_PATH=/config/youtube_cookies.txt \
  -v <VIDEOS_FOLDER_DOCKER_HOST>:/data/videos \
  -v <TMP_DOWNLOAD_FOLDER_DOCKER_HOST>:/data/tmp \
  -v <YOUTUBE_COOKIES_FILE_PATH_DOCKER_HOST>:/config \
  ghcr.io/egalitarianmonkey/hometube:latest

--env-file .env

docker run -p 8501:8501 \
  --env-file .env \
  -v <VIDEOS_FOLDER_DOCKER_HOST>:/data/videos \
  -v <TMP_DOWNLOAD_FOLDER_DOCKER_HOST>:/data/tmp \
  -v <YOUTUBE_COOKIES_FILE_PATH_DOCKER_HOST>:/config \
  ghcr.io/egalitarianmonkey/hometube:latest

Access at http://localhost:8501

With Docker compose, environment variables can be passed either with the environment: entry or from the convenient .env file with env_file: .env.

.env

# --- PORT ---
PORT=8510

# --- Timezone ---
TZ=America/New_York

# --- Languages ---
UI_LANGUAGE=en
LANGUAGE_PRIMARY=en
LANGUAGE_PRIMARY_INCLUDE_SUBTITLES=true
LANGUAGES_SECONDARIES=  # Optional: comma-separated (e.g., fr,es)

# --- Docker host paths ---
# Docker environment variables to specify depending on your homelab setup.
VIDEOS_FOLDER_DOCKER_HOST=/mnt/data/videos
TMP_DOWNLOAD_FOLDER_DOCKER_HOST=/mnt/data/hometube/tmp
YOUTUBE_COOKIES_FILE_PATH_DOCKER_HOST=/opt/cookies/youtube.txt

# --- Paths ---
# Internal Docker container paths (do not change)
VIDEOS_FOLDER=/data/videos
TMP_DOWNLOAD_FOLDER=/data/tmp
YOUTUBE_COOKIES_FILE_PATH=/config/youtube_cookies.txt
#COOKIES_FROM_BROWSER=brave # Not working natively in Docker

docker-compose.yml

services:
  hometube:
    image: ghcr.io/egalitarianmonkey/hometube:latest
    env_file: .env
    volumes:
      - type: bind
        source: ${VIDEOS_FOLDER_DOCKER_HOST:?set VIDEOS_FOLDER_DOCKER_HOST}
        target: /data/videos
      - type: bind
        source: ${TMP_DOWNLOAD_FOLDER_DOCKER_HOST:?set TMP_DOWNLOAD_FOLDER_DOCKER_HOST}
        target: /data/tmp
      - "${YOUTUBE_COOKIES_FILE_PATH_DOCKER_HOST}:/config/youtube_cookies.txt"

This long volume structure with type:, source:, and target: entries forces the environment variables to be set, otherwise the Docker deployment fails. This avoids silent failures and confusions when environment variables are missing.

docker-compose.yml

services:
  hometube:
    image: ghcr.io/egalitarianmonkey/hometube:latest
    environment:
      UI_LANGUAGE: en
      LANGUAGE_PRIMARY: en
      LANGUAGE_PRIMARY_INCLUDE_SUBTITLES: true
      LANGUAGES_SECONDARIES: ""  # Optional: comma-separated
      VIDEOS_FOLDER: /data/videos
      TMP_DOWNLOAD_FOLDER: /data/tmp
      YOUTUBE_COOKIES_FILE_PATH: /config/youtube_cookies.txt
    volumes:
      - type: bind
        source: ${VIDEOS_FOLDER_DOCKER_HOST:?set VIDEOS_FOLDER_DOCKER_HOST}
        target: /data/videos
      - type: bind
        source: ${TMP_DOWNLOAD_FOLDER_DOCKER_HOST:?set TMP_DOWNLOAD_FOLDER_DOCKER_HOST}
        target: /data/tmp
      - "${YOUTUBE_COOKIES_FILE_PATH_DOCKER_HOST}:/config/youtube_cookies.txt"

This long volume structure with type:, source:, and target: entries forces the environment variables to be set, otherwise the Docker deployment fails. This avoids silent failures and confusions when environment variables are missing.

Access at http://localhost:8501

With Portainer, environment variables must be explicitly written in the environment: section of the container setup to get those environment variables in the app.

• It does not support env_file: entry for passing environment variables in the container from a .env file involving that the environment variables must be explicitly written in the environment: section of the container setup to get those environment variables in the app.
• It does not retrieve any Docker environment variables from a .env file as the stack isn't linked to any location. Environment variables for the Portainer docker-compose.yml stack must be manually entered from the UI either one by one or with a convenient .env upload.

docker-compose.yml

services:
  hometube:
    image: ghcr.io/egalitarianmonkey/hometube:latest
    ports:
      - "${PORT:-8501}:8501"
    environment:
      TZ: "${TZ}"
      UI_LANGUAGE: en
      LANGUAGE_PRIMARY: en
      LANGUAGE_PRIMARY_INCLUDE_SUBTITLES: true
      LANGUAGES_SECONDARIES: ""  # Optional: comma-separated
      VIDEOS_FOLDER: /data/videos
      TMP_DOWNLOAD_FOLDER: /data/tmp
      YOUTUBE_COOKIES_FILE_PATH: "${YOUTUBE_COOKIES_FILE_PATH}"
    volumes:
      - type: bind
        source: ${VIDEOS_FOLDER_DOCKER_HOST:?set VIDEOS_FOLDER_DOCKER_HOST}
        target: /data/videos
      - type: bind
        source: ${TMP_DOWNLOAD_FOLDER_DOCKER_HOST:?set TMP_DOWNLOAD_FOLDER_DOCKER_HOST}
        target: /data/tmp
      - "${YOUTUBE_COOKIES_FILE_PATH_DOCKER_HOST}:/config/youtube_cookies.txt"

This long volume structure with type:, source:, and target: entries forces the environment variables to be set, otherwise the Docker deployment fails. This avoids silent failures and confusions when environment variables are missing.

Portainer environment variables in the UI

VIDEOS_FOLDER_DOCKER_HOST=/mnt/data/videos
TMP_DOWNLOAD_FOLDER_DOCKER_HOST=/mnt/data/hometube/tmp
YOUTUBE_COOKIES_FILE_PATH_DOCKER_HOST=/opt/cookies/youtube.txt
TZ=America/New_York
PORT=8501
YOUTUBE_COOKIES_FILE_PATH=/config/youtube_cookies.txt
#COOKIES_FROM_BROWSER=chrome

Environment variables for local run are setup following a specific order:

• First, defined and exported environment variables from the current shell will be taken (export VIDEOS_DIR=/data/videos, set -a && source .env && set +a, etc.)
• Then, if a .env file exists, not defined environment variables from exported shell will be taken from local .env file
• At last, default values will be used for not defined environment variables from shell and .env file

Prerequisites are installed through python environment setup. Below are setups for venv, conda, or uv.

Option 1: Using pip (Recommended)

# Create virtual environment
python -m venv hometube-env
source hometube-env/bin/activate  # On Windows: hometube-env\Scripts\activate

# Install dependencies including yt-dlp
pip install ".[local]"

# Run the application
streamlit run app/main.py
# OR
python run.py

Option 2: Using conda

# Create conda environment
conda create -n hometube python=3.10
conda activate hometube

# Install dependencies including yt-dlp
pip install ".[local]"

# Run the application
streamlit run app/main.py

Option 3: Using uv (Fastest)

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies including yt-dlp
uv pip install ".[local]"

# Run with uv
uv run streamlit run app/main.py

Access at: http://localhost:8501

HomeTube configuration is managed through the .env file:

Check your setup with this command:

DEBUG=1 python -c "import app.main" 2>/dev/null

Expected output:

🔧 HomeTube Configuration Summary:
📁 Videos folder: downloads
📁 Temp folder: tmp
✅ Videos folder is ready: downloads
🍪 Cookies file: ./cookies/youtube_cookies.txt
🔤 Subtitle languages: en, fr
✅ Configuration file: .env

📋 Complete Documentation Hub: docs/README.md

• Installation Guide - System setup and requirements
• Usage Guide - Complete feature walkthrough
• Docker Guide - Container deployment strategies

• Development Setup - Multi-environment development guide
• UV Workflow Guide - Modern dependency management
• Testing Documentation - Test framework and guidelines
• Deployment Guide - Production deployment strategies

• ✅ Stable: Core functionality tested and reliable
• 🔄 Active Development: Regular updates and improvements
• 🧪 Test Coverage: 84% on testable modules (details)
• 📦 Production Ready: Docker images available on GHCR
• 🏠 HomeLab Optimized: Designed for self-hosted environments

Check out the roadmap for upcoming features and enhancements:

📋 See the complete roadmap: docs/todo.md

For developers and contributors, comprehensive guides are available:

📖 Development Setup Guide - Environment setup
🔄 Contributing Guidelines - Workflow and best practices

Quick Setup Options:

• Conda (recommended for contributors)
• UV (fastest for developers)
• pip/venv (universal)

Includes: Testing commands, workflows, code standards, and pull request process.

If you find HomeTube useful, consider supporting the project to help with development costs.

This project is licensed under the AGPL-3.0 License - see the LICENSE file for details.

• yt-dlp - Universal video downloader supporting 1800+ platforms
• Streamlit - Excellent web app framework
• SponsorBlock - Community-driven sponsor detection (YouTube)
• FFmpeg - Multimedia processing framework