MeTube

MeTube is a self-hosted web UI for yt-dlp. Paste a link from YouTube or hundreds of other sites, and it downloads to your server:

• Video, audio, subtitles and thumbnails — from single videos, whole playlists or entire channels.
• Subscriptions to channels and playlists, which queue new uploads as they appear.
• Per-download choices of quality, format and folder, plus server-wide yt-dlp options and presets.

📖 Guides, recipes and a troubleshooting FAQ live in the wiki — many feature requests are already a recipe there, so check it before filing one.

Quick start

docker run -d -p 8081:8081 -v /path/to/downloads:/downloads ghcr.io/alexta69/metube

Or with Docker Compose:

services:
  metube:
    image: ghcr.io/alexta69/metube
    container_name: metube
    restart: unless-stopped
    ports:
      - "8081:8081"
    volumes:
      - /path/to/downloads:/downloads

Then open http://<host>:8081 in your browser. Images are multi-arch (amd64/arm64), and also published on Docker Hub as alexta69/metube.

Configuration

MeTube is configured with environment variables: -e NAME=value on the docker run command line, or the environment: section in Compose. Defaults are the Docker image's; outside Docker, the directories default to the working directory.

Runtime and permissions

Downloads

Directories

File naming

Templates use yt-dlp's output template syntax. How MeTube applies them is explained in Output templates.

yt-dlp

Web server and network

yt-dlp options

yt-dlp options are JSON objects keyed by yt-dlp's API option names, which differ from its command-line flags (converter). They apply at three levels, and for an option set at more than one, the more specific level wins:

1. Global — YTDL_OPTIONS and YTDL_OPTIONS_FILE, for every download.
2. Presets — YTDL_OPTIONS_PRESETS and YTDL_OPTIONS_PRESETS_FILE, picked per download under Advanced Options.
3. Overrides — typed into the UI for a single download, when ALLOW_YTDL_OPTIONS_OVERRIDES is on.

environment:
  - 'YTDL_OPTIONS={"writesubtitles": true, "subtitleslangs": ["en", "de"], "updatetime": false}'

The yt-dlp options guide covers presets, overrides and option files in detail, and the YTDL_OPTIONS Cookbook has ready-made recipes.

Guides

The wiki covers everything beyond the reference above:

• Subscriptions — download new uploads from channels and playlists automatically.
• yt-dlp options and the YTDL_OPTIONS Cookbook — notifications, embedded metadata, subtitles and more.
• Output templates and the OUTPUT_TEMPLATE Cookbook — how files are named and sorted into folders.
• Using browser cookies — for private, age-restricted and "confirm you're not a bot" videos.
• Sending links to MeTube — browser extensions, bookmarklets, iOS and Android apps, Raycast.
• HTTPS and reverse proxies — NGINX, Apache, Caddy and swag examples, and adding authentication.
• Hardware-accelerated transcoding — re-encode downloads on an Intel or AMD GPU.
• yt-dlp plugins — extend yt-dlp, e.g. to accept links from Invidious or Piped.
• Troubleshooting FAQ — common problems and how to diagnose them.

Keeping yt-dlp up to date

Sites change constantly, and yt-dlp keeps up with frequent releases. A new MeTube image is published automatically for every yt-dlp stable release, so keep your container updated — watchtower can do it for you. To follow yt-dlp's nightly builds instead, set YTDL_NIGHTLY_UPDATE_TIME.

Troubleshooting and support

MeTube is only a UI for yt-dlp, so most download failures are yt-dlp's. Reproduce them with yt-dlp inside the container, and once a set of options works there, carry it over to YTDL_OPTIONS:

docker exec -ti metube sh
cd /downloads
yt-dlp <url>

The Troubleshooting FAQ covers common problems. Ask questions in Discussions; issues are for bugs in MeTube itself.

Scope and contributing

MeTube's scope is deliberately narrow: it downloads well, and stops once the file is written. Tagging and library organization belong to dedicated tools — point beets (headless, scriptable), MusicBrainz Picard (GUI, acoustic fingerprinting) or Lidarr (full library manager) at your AUDIO_DOWNLOAD_DIR.

Feature requests that fit this scope are welcome, and so are pull requests — for a change that isn't obvious, start a discussion first. CONTRIBUTING.md has the scope policy and how to build and run MeTube locally.