HomeTube for self-hosted video libraries

HomeTube's role in a Plex or Jellyfin library

HomeTube addresses the gap between finding a video online and placing it where a media server already expects local media. Its intended user is a homelab operator who wants a browser UI rather than a collection of yt-dlp commands entered on a server. The interface accepts a single video URL or a playlist, chooses a quality strategy or a manual override, processes the result, and writes it to a configured destination. That destination is intended to be watched by Plex, Jellyfin, or Emby.

The important point is organization rather than playback. HomeTube does not replace a media server or provide a catalog database of its own. It creates files and names them for an existing library. This makes it useful when the surrounding infrastructure is already designed around mounted storage and media-server scanning. It is less suitable when the desired result is an account-based cloud video service or a completely unattended feed.

The README also describes a browser-hosted HomeTube service with an email sign-in and free quota. That hosted option is separate from the self-hosted repository. An operator evaluating this code should focus on the Docker deployment and local storage model rather than confusing the hosted service with the application they will run themselves.

URL-to-library flow inside HomeTube

The documented workflow starts with a URL and moves through download and processing before placement in a media-server directory. The README says HomeTube supports single videos and playlists, with quality selection ranging from an automatic best-quality strategy to a manual override. It also documents subtitles, clipping, format conversion, and custom yt-dlp arguments. Those options indicate that the application is more than a thin URL form around one download command.

SponsorBlock support is built into the YouTube workflow. The README says sponsor and advertising segments are detected and can be blocked or marked, using SponsorBlock's community-maintained database. This feature should be understood as segment processing, not as a general promise that every advertisement in every source platform will be removed. The documentation specifically presents zero-configuration behavior for YouTube videos.

Caching is described as URL analysis reuse with quality verification. According to the README, HomeTube can avoid downloading metadata again unless a better format quality is available. That is useful for repeated operations, although the README does not define cache invalidation behavior, storage limits, or what happens when source formats change. Cookie authentication is supported and is described as important for restricted content and signature errors. The sample environment expects a cookies file at a configured path, so authenticated downloads require deliberate filesystem and secret handling.

Docker deployment and local path configuration

HomeTube documents Docker Compose as its deployment path for a homelab. The repository contains `Dockerfile` and `docker-compose.yml.sample`, while the sample environment file supplies the host and container paths that connect the application to external storage. The values below are copied from `.env.sample`. They are examples, not universal defaults, so change the host paths to match the machine running Docker.

For a local installation, copy the sample environment settings into the environment file used by your deployment, then adjust the Docker host locations. The container-facing paths are intentionally separate from the host paths because Docker must be able to see the same directories under its own mount namespace.

The sample configuration uses these values:

PORT=8510
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
VIDEOS_FOLDER=/data/videos
TMP_DOWNLOAD_FOLDER=/data/tmp
YOUTUBE_COOKIES_FILE_PATH=/config/youtube_cookies.txt

The repository declares `make install`, `make run`, `make docker-build`, and `make docker-up` targets. The Makefile declares those targets, but it does not show their complete recipes, so the Compose deployment remains the precise path to consult in `docker-compose.yml.sample` and `docs/deployment.md`. Do not assume that a target exists merely because it appears in the development command list.

A first download through the HomeTube interface

After the container is reachable, the first real use is a browser workflow. Open the configured HomeTube address, paste one supported video URL, select a destination, and choose either automatic quality selection or a manual quality profile. The README also describes a UI option for creating a new destination folder, with examples such as `Tech/Python/Advanced`. Select a destination that the media server already scans.

For a clean first request, use a single video rather than a playlist. This reduces the number of possible outcomes and makes it easier to inspect the resulting filename, subtitle handling, and destination. If the source requires authentication, configure the cookies file before submitting the URL. The README recommends cookies for restricted content and signature errors.

After the download completes, inspect the mounted destination from the Docker host. Confirm that the final file is in the expected library tree and that Plex, Jellyfin, or Emby can see the mounted volume. The application documentation describes automatic placement, but it does not promise that every media server will recognize every filename or directory convention. Your server's naming and library settings remain part of the integration.

The interface also exposes advanced yt-dlp arguments. The sample environment includes this commented setting:

#YTDLP_CUSTOM_ARGS=--max-filesize 100M --write-info-json

Use it only when the required behavior is understood. Custom arguments can change file selection, output files, or network behavior, and HomeTube does not assume that every third-party yt-dlp option fits its processing pipeline.

Source coverage, media processing, and failure boundaries

The README names YouTube, Reddit, Vimeo, Dailymotion, TikTok, Twitch, Facebook, and Instagram, and points to `docs/supported-platforms.md` for a list of more than 1,800 sources. That breadth comes from the underlying downloader ecosystem rather than from a promise that every site behaves identically. Authentication requirements, changing pages, geographic restrictions, rate limits, and unavailable formats can still affect individual URLs.

HomeTube also supports downloading through yt-dlp, with the project metadata specifying `yt-dlp>=2025.9.23` for local installations. The Docker image is based on `jauderho/yt-dlp:latest`. Its Dockerfile explicitly notes that the base is deliberately unpinned so a new yt-dlp release can reach users through a rebuild. That choice reduces manual version bumps, but it also means the base image can change. The Dockerfile calls out a past change involving the preinstalled pip and Python 3.14 as an example of why the installation step avoids assumptions beyond `python3`.

For users who need byte-for-byte reproducibility, that rolling base image is a meaningful constraint. Pinning or rebuilding images requires an operational policy outside what the README documents. HomeTube's own Python metadata requires Python 3.11 or later and constrains Streamlit to `>=1.49,<1.65`.

The project is also not an unattended channel manager. The README describes playlist synchronization and one-click downloads, but it does not explain scheduler configuration, retry policy, notification behavior, or rollback after a failed playlist update. Those omissions matter for a service expected to run continuously.

HomeTube compared with direct yt-dlp and the Content engine

Direct yt-dlp use is the clearest alternative for a technical operator who already knows downloader options. A direct command can target one URL, select formats, write subtitles, and place an output file without introducing a Streamlit UI or a media-library workflow. It requires less application-level configuration, but it also means manually composing arguments, interpreting output, and maintaining a repeatable naming and storage convention.

HomeTube's difference is the surrounding control plane. The interface turns URL submission, quality policy, destination selection, cookies, SponsorBlock handling, and post-processing into a browser workflow. That is more convenient for a household or homelab where several people need a repeatable path to a shared media library. It adds a Python application, a persistent configuration surface, and an operational dependency on HomeTube itself.

The README also points to `LatentNoise/content`, described as a newer self-hosted engine accepting URLs, files, and text and producing media, transcripts, summaries, translations, and documents. It includes a REST API, Python SDK, CLI, browser extension, MCP server, and its own HomeTube app. This is a materially different approach: it expands from media-library downloading into a general content-processing platform. HomeTube remains the narrower choice for organized video placement, while Content is the documented direction for broader input and output types.

Maintenance, upgrades, and the AGPL boundary

The repository is not archived, and its last push was on 2026-10-15. The recent release history includes `v2.13.0` on 2026-09-22, `v2.12.3` on 2026-09-17, and `v2.12.2` on 2026-09-14. These dates indicate recent project activity, but they do not establish compatibility with every deployment or every upstream service.

Upgrade work has two layers. Python dependencies are described in `pyproject.toml`, with separate `local`, `docker`, `test`, and `dev` optional groups. The Dockerfile's rolling yt-dlp base introduces a second layer of change. Operators who rebuild automatically may receive a different downloader environment without changing the HomeTube version string. The repository includes dependency synchronization and update targets, but the README does not define a production rollback procedure.

HomeTube is licensed under `AGPL-3.0-or-later`, and `pyproject.toml` declares `AGPL-3.0-or-later` with `LICENSE` and `NOTICE`. That matters for organizations considering network use or modifications. This article does not provide legal advice, but the license text and notice should be reviewed before redistributing a modified service or exposing a network-accessible deployment. The stated license does not imply permission to ignore the AGPL's source and network-use obligations.

Editorial conclusion

HomeTube fits homelab operators who want a browser interface for sending video URLs into a Plex, Jellyfin, Emby, or local library. It is a poor fit for users who need a fully unattended subscription service, a supported command-line-only deployment, or a permissive license. Before adopting it, verify that your Docker host paths, destination volume, cookies file, selected quality profile, and media-server library rules work with your intended directory structure.

Frequently asked questions

Official sources

1. EgalitarianMonkey/hometube on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases