Skip to main content

Install

Up and running in under a minute.

Docker Compose is the recommended path. It works on any box that runs containers, from a Raspberry Pi to a Proxmox cluster.

Requirements

  • Docker with Compose
  • A videos folder your media server watches
  • A YouTube cookies file (recommended)
  • Internet access from the host

Docker Compose

Persistent, configurable through a .env file

Recommended

1. Clone, configure, start:

terminal 
git clone https://github.com/EgalitarianMonkey/hometube.git
cd hometube
cp .env.sample .env      # edit the *_DOCKER_HOST paths
docker compose up -d

2. The minimal .env (three host paths are mandatory):

.env 
# --- Docker host paths (adapt to your 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

# --- Container paths (do not change) ---
VIDEOS_FOLDER=/data/videos
TMP_DOWNLOAD_FOLDER=/data/tmp
YOUTUBE_COOKIES_FILE_PATH=/config/youtube_cookies.txt

# --- Preferences ---
PORT=8501
TZ=Europe/Paris
UI_LANGUAGE=en
LANGUAGE_PRIMARY=en
LANGUAGES_SECONDARIES=          # e.g. fr,es
Prefer writing your own docker-compose.yml?
docker-compose.yml 
services:
  hometube:
    image: ghcr.io/egalitarianmonkey/hometube:latest
    env_file: .env
    ports:
      - "${PORT:-8501}:8501"
    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"
    restart: unless-stopped

The long type / source / target volume form makes Compose fail loudly when a host path variable is missing, instead of silently creating an empty folder.

Then open http://localhost:8501 (or your host's IP from any device on the network).

docker run

One command, explicit variables

terminal 
docker run -d --name hometube \
  -p 8501:8501 \
  -e TZ=Europe/Paris \
  -e VIDEOS_FOLDER=/data/videos \
  -e TMP_DOWNLOAD_FOLDER=/data/tmp \
  -e YOUTUBE_COOKIES_FILE_PATH=/config/youtube_cookies.txt \
  -v /mnt/data/videos:/data/videos \
  -v /mnt/data/hometube/tmp:/data/tmp \
  -v /opt/cookies/youtube.txt:/config/youtube_cookies.txt \
  ghcr.io/egalitarianmonkey/hometube:latest

Local (Python)

Python 3.10+, ffmpeg, uv or pip

terminal 
git clone https://github.com/EgalitarianMonkey/hometube.git && cd hometube
cp .env.sample .env
uv sync                          # or: python -m venv .venv && pip install ".[local]"
uv run streamlit run app/main.py # http://localhost:8501

Locally, COOKIES_FROM_BROWSER=brave (or chrome, firefox…) can replace the cookies file.

Works on your favourite platform

Anything that runs Docker. With Portainer, paste the Compose file as a stack and enter the *_DOCKER_HOST variables in the stack's environment section.

  • Synology
  • QNAP
  • Unraid
  • TrueNAS
  • Proxmox
  • Portainer

Updating

Images are tagged per release; latest follows the newest one.

terminal 
docker compose pull && docker compose up -d

FAQ

Common questions

How do I update HomeTube?

Pull the latest image and recreate the container: docker compose pull && docker compose up -d. Your videos, temporary folder and cookies live in the mounted volumes and are untouched.

Why do I need a cookies file for public YouTube videos?

YouTube protects many streams with signatures and anti-bot checks, even for public videos. A cookies file exported from a logged-in browser unlocks the best formats, age-restricted and members-only content, and avoids most 'format unavailable' errors.

Which port does HomeTube use?

The web UI listens on 8501 inside the container. Map it to any host port with PORT in .env. If you run Content's HomeTube app on the same machine, change one of the two ports.

Can I change the download folder or add several destinations?

Mount the root of your library on /data/videos. Every sub-folder becomes a destination choice in the UI, and you can create new sub-folders from the destination menu.

Does it run on ARM (Raspberry Pi, Apple Silicon, ARM NAS)?

Yes. The image is published for amd64 and arm64 on GitHub Container Registry.

How do I get help or report a bug?

Open an issue on GitHub, or ask on r/HomeTube. Include the container logs and the URL that fails if you can.

Full installation docs Open an issue

Or install Content

HomeTube plus transcripts, summaries and documents

Content bundles a new HomeTube app on a shared engine with Content Studio, a console, an API and more. Same Docker Compose habit, nothing to build.

terminal 
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   # HomeTube :8501 · Studio :8502 · Console :8503 · API :8010
What is Content? Deployment guide