🎬 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+)

🛠️ HomeTube Options

🏠 HomeLab Integration

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.

🚫 Block all ads and sponsors

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 (Highly Recommended)

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

🚨 Why Cookies Are Essential

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.

🛠️ Setup Options

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

More details about Cookies authentication setup.

✂️ Advanced Video Processing

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.

🔧 Advanced configurations

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.

🎯 Smart Quality System

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

🎯 Smart Download Management

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.

📋 Intelligent Playlist Management

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.

🌐 Universal Platform Support

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.

🚀 Quick Start

⚙️ Essential Configuration

📋 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

🐳 Docker

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

🐳 Docker Compose

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

Configuration with .env file

.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.

Configuration with environment::

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

🐳 Portainer

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

Portainer environment variables management

• 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

🏠 Local Installation

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

⚙️ Configuration Guide

🔧 Environment Variables

HomeTube configuration is managed through the .env file:

🔄 Configuration Validation

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

📚 Documentation

📋 Complete Documentation Hub: docs/README.md

Core Guides

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

Development & Operations

• Development Guide - Multi-environment setup (pip, conda, uv)
• Contributing Guide - Workflow, standards, pull requests
• Testing Documentation - Test framework and guidelines
• Deployment Guide - Production deployment strategies

🛠️ Tech Stack

📊 System Requirements

📈 Project Status

• ✅ Stable: Core functionality tested and reliable
• 🔄 Active Development: Regular updates, fixes and fresh yt-dlp releases
• 🧪 Test Coverage: 358 tests, 22% of statements across app/, concentrated on the utility modules (details)
• 📦 Production Ready: Docker images available on GHCR
• 🏠 HomeLab Optimized: Designed for self-hosted environments
• 🌱 Next generation: The platform it grew into is Content

🌱 What comes next: Content

HomeTube does one job well: getting videos from the internet into a clean, self-hosted library. That workflow has grown into a platform.

Content is a new self-hosted engine built on the same idea, taken further — URLs, files and text in; media, transcripts, summaries, translations, images, Markdown and PDF out. One backend, several independent front doors:

Where things stand. HomeTube is the mature one and keeps being developed — this release is one of them. Content is the newer, broader engine, and it is where the most ambitious capabilities are being built: everything above is available today, and the two run happily side by side. Try it whenever you are curious.

Two honest caveats before you do:

• Playlist synchronization has not made the trip yet. Content downloads playlists — every item analyzed and planned on its own, named per item, delivered as its own artifact — but the plan/apply sync that keeps a local folder in step with a playlist over time (rename detection, archiving removed videos, relocation) is HomeTube-only for now. It is on Content's roadmap. If that is your main use, stay here for it.
• Both default to port 8501. Change one of them if you want to run the two side by side.

mkdir content && cd content
curl -fsSLO https://raw.githubusercontent.com/LatentNoise/content/main/deploy/docker-compose.yml
curl -fsSL -o .env https://raw.githubusercontent.com/LatentNoise/content/main/.env.example
docker compose up -d

🤝 Contributing & Development

For developers and contributors, comprehensive guides are available:

📖 Development 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.

☕ Support This Project

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

📄 License

HomeTube is free software under the GNU Affero General Public License, version 3 or later — see LICENSE for the full text.

Copyright © 2025-2026 Yann Orieult, sole author and maintainer. NOTICE records copyright and licensing, AUTHORS records authorship, and CONTRIBUTING.md sets out the terms that apply to contributions.

🙏 Acknowledgments

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