MeTube: A Self-Hosted Web UI for yt-dlp That Puts Downloads Behind a Clean Interface

What MeTube Actually Solves

MeTube is a self-hosted web UI for yt-dlp, the command-line tool that downloads media from YouTube and dozens of other sites. The problem it solves is that yt-dlp is a CLI: you either type commands, write scripts, or use a third-party front end. MeTube gives you a browser interface to queue downloads, pick formats, and manage playlists and channels. It is aimed at people who run a home server or a small media box and want to initiate downloads from a phone or another machine without SSH. The README lists downloads of videos, audio, captions, and thumbnails, plus playlist and channel handling. It also supports subscriptions: you can subscribe to a channel or playlist, and MeTube periodically checks for new items and queues them automatically. That subscription feature is the main differentiator over a plain yt-dlp cron job, because it maintains state and avoids re-downloading seen videos.

How MeTube Works Under the Hood

MeTube is a Python application that wraps yt-dlp. The Docker image runs a web server on port 8081 and mounts a downloads directory. When you submit a URL through the UI, MeTube invokes yt-dlp with options that you can control via environment variables. The README shows state files named queue.json, pending.json, completed.json, and subscriptions.json, stored in STATE_DIR. This tells you the architecture: a persistent queue of pending downloads, a record of completed ones, and a subscription registry. The queue is processed with a concurrency limit, set by MAX_CONCURRENT_DOWNLOADS, which defaults to 3. Downloads beyond that wait. The subscription mechanism runs on an interval, defaults to 60 minutes, and scans up to SUBSCRIPTION_SCAN_PLAYLIST_END entries per check, newest first. It stores a cap of 50000 video IDs per subscription to keep state files from growing without bound. That cap is a concrete design choice: it prevents unbounded state growth but means very old videos in a subscription will eventually be forgotten, so if you unsubscribe and resubscribe, you might re-download old items.

Getting MeTube Running: Docker and Configuration

The quickest start is a single Docker command: docker run -d -p 8081:8081 -v /path/to/downloads:/downloads ghcr.io/alexta69/metube. A Docker Compose example is also provided. Configuration is entirely via environment variables. The runtime variables include PUID and PGID for user and group, UMASK, DEFAULT_THEME for light, dark, or auto, and LOGLEVEL. Download behavior is tuned with MAX_CONCURRENT_DOWNLOADS, DELETE_FILE_ON_TRASHCAN, and DEFAULT_OPTION_PLAYLIST_ITEM_LIMIT. Storage is controlled by DOWNLOAD_DIR, AUDIO_DOWNLOAD_DIR, STATE_DIR, and TEMP_DIR. The README recommends setting TEMP_DIR to an SSD or RAM filesystem for performance, but notes that using a RAM filesystem may prevent downloads from being resumed. That is a real trade-off: speed versus resumability. File naming is handled by OUTPUT_TEMPLATE and its playlist and channel variants, using yt-dlp's output template spec. You can also pass arbitrary yt-dlp options via YTDL_OPTIONS as a JSON object, and YTDL_OPTIONS_FILE points to a JSON file that is monitored and reloaded automatically on changes. That hot-reload is a useful operational feature, but it only works if you are comfortable editing JSON files on the server.

Subscriptions and Custom Directories: The Features That Matter

Subscriptions are the feature that justifies MeTube over a bare yt-dlp wrapper. You subscribe to a channel or playlist, and MeTube checks for new items on an interval. The default check interval is 60 minutes, and you can adjust it per subscription or globally via SUBSCRIPTION_DEFAULT_CHECK_INTERVAL. The scan limit of 50 entries per check means very active channels might miss uploads if more than 50 new videos appear between checks, but that is an edge case. Custom directories are another notable feature. CUSTOM_DIRS defaults to true, which adds a Download Folder field under Advanced Options. CREATE_CUSTOM_DIRS defaults to true, allowing free-text input and recursive creation of directories. This is convenient but also a footgun: if you leave it enabled, a user who mistypes a directory name will create a new folder on the server. The regex CUSTOM_DIRS_EXCLUDE_REGEX defaults to (^|/)[.@].*$, which hides dot-directories and @-directories from suggestions, but it does not prevent free-text creation. If you want to lock down the download location, set CUSTOM_DIRS to false.

Limitations and Failure Modes

MeTube inherits yt-dlp's fragility: if yt-dlp breaks due to a site change, MeTube will fail until the underlying tool is updated. The README does not mention any built-in update mechanism for yt-dlp, so you are responsible for keeping the Docker image current. The release cadence shown in the repository is weekly or more frequent, which suggests active maintenance, but that also means you need to track releases. Another limitation is that the UI abstracts yt-dlp options. You can pass raw options via YTDL_OPTIONS, but that requires JSON knowledge and is not discoverable from the UI. For users who need complex post-processing, like embedding metadata or converting formats, the presets feature (YTDL_OPTIONS_PRESETS) helps, but it still requires manual JSON configuration. The CLEAR_COMPLETED_AFTER variable defaults to 0, meaning completed and failed downloads stay in the Completed list forever unless you set a timeout. That can clutter the UI over time. Also, the README notes that using a RAM filesystem for TEMP_DIR prevents download resumption, so if you prioritize reliability over speed, avoid tmpfs.

Alternatives: yt-dlp CLI and Other Web UIs

The most direct alternative is using yt-dlp directly from the command line. It gives you full control over output templates, postprocessors, cookies, and format selection without a web server. The trade-off is that you lose the browser UI, the subscription state management, and the queue. If you only need occasional downloads, the CLI is simpler and has no extra moving parts. Another alternative is Tube Archivist, which is a full YouTube media management system with its own database and UI. Tube Archivist focuses on archiving entire channels with metadata and search, whereas MeTube is a downloader that saves files to disk without a media library. If you want a permanent archive with search, Tube Archivist is a different approach. For a lighter option, you could write a cron job that calls yt-dlp with a playlist URL, but you would have to handle deduplication yourself. MeTube's subscription state files are exactly that deduplication logic, so the comparison is between building your own script versus running a ready-made service.

Maintenance, Licensing, and Upgrade Cost

MeTube is licensed under AGPL-3.0, which means if you modify and distribute it, you must share your source code. For personal self-hosting, this is rarely a concern, but it matters if you plan to offer a service based on it. The repository shows active releases, with three releases in August 2026 alone. That suggests a project that is maintained, but it also means you should expect frequent updates. The upgrade cost is low if you use Docker: pull the new image and restart the container. However, you should check the release notes for changes to environment variables or state file formats. The state files in STATE_DIR are persistent, so your queue and subscriptions survive upgrades, but a major version change could alter their schema. The README does not document a migration path, so before upgrading, back up the STATE_DIR directory. The multi-arch Docker images (amd64/arm64) make it easy to run on a Raspberry Pi or an ARM NAS, which is a practical advantage for home server users.

Editorial conclusion

Adopt MeTube if you want a browser-based download manager for yt-dlp that runs in Docker, supports multi-arch images, and can automate channel subscriptions without writing scripts. Skip it if you are comfortable with yt-dlp's CLI or need fine-grained control over every download option, since MeTube's UI abstracts but does not replace yt-dlp's complexity. Before deploying, verify that your storage layout matches the DOWNLOAD_DIR, STATE_DIR, and TEMP_DIR defaults, and decide whether CUSTOM_DIRS should stay enabled to avoid accidental folder creation. Check the AGPL-3.0 license if you plan to modify or embed the project.

Official sources

1. Official README
2. Project repository
3. Release notes