MeTube

Last reviewed Aug 26, 2026 · 764 words

services:
  metube:
    image: ghcr.io/alexta69/metube
    ports:
      - "8081:8081"
    environment:
      - UID=1000
      - GID=1000
      - OUTPUT_TEMPLATE=%(uploader)s/%(title)s.%(ext)s
    volumes:
      - /srv/media/youtube:/downloads
    restart: unless-stopped

That is a complete MeTube install. Open port 8081, paste a URL, pick a format, and the file lands in /srv/media/youtube/{channel}/{title}.mp4. MeTube is a thin web interface over yt-dlp, the command-line downloader that handles YouTube and hundreds of other sites, and it makes no attempt to be more than that: 14,518 stars, AGPL-3.0, one container, about 256 MB of RAM including a running download. The interesting decisions are the three environment variables above, and the one operational habit below.

The output template decides whether Jellyfin can read it

The default template is %(title)s.%(ext)s, which dumps every video into one flat folder. That is fine for watching once and deleting. If downloads are going into a library that Jellyfin scans, the %(uploader)s/%(title)s.%(ext)s template gives you a folder per channel, which Jellyfin's "Home Videos" or "Mixed Content" library types index cleanly. MeTube exposes yt-dlp's full template syntax, so %(upload_date)s for date prefixes or %(playlist_title)s for playlists all work. Set AUDIO_DOWNLOAD_DIR if you want audio extractions in a separate tree, and match UID and GID to the user that owns the media share or Jellyfin will see files it cannot open.

Every yt-dlp option is available through one variable

Anything you would put on a yt-dlp command line goes into YTDL_OPTIONS as JSON. The two settings I always add are SponsorBlock and a cookies file:

      - YTDL_OPTIONS={"cookiefile":"/cookies/cookies.txt","postprocessors":[{"key":"SponsorBlock","when":"after_filter"},{"key":"ModifyChapters","remove_sponsor_segments":["sponsor","selfpromo"]}]}

Mount the cookies file read-only from a browser export. Cookies matter more each year: YouTube increasingly rate-limits or challenges anonymous downloaders, and age-restricted or members-only videos never work without them. Subtitles ("writesubtitles": true), embedding thumbnails, and format preferences all go in the same place. Keep the JSON on one line; Compose does not parse multi-line values the way you hope.

Update the image or it stops working

yt-dlp is in a permanent arms race with the sites it downloads from, and a two-month-old MeTube image will start failing on YouTube with cryptic extraction errors. That is not a MeTube bug and no configuration fixes it. The MeTube maintainer rebuilds the image whenever yt-dlp releases, so the fix is to pull often: point Watchtower at the container, or add docker compose pull && docker compose up -d to a weekly cron. Of everything in this guide, this is the item that determines whether the tool works in six months.

What MeTube is not

There is no subscription model: it will not watch a channel and fetch new uploads. There is no metadata database, no per-video notes, no deduplication, and no multi-user separation; anyone who can reach port 8081 can download to your disk, so keep it behind your VPN or an authenticating proxy. If you want a self-hosted archive that follows channels, indexes metadata, and integrates with Jellyfin as a first-class source, Tube Archivist is the heavier answer and Pinchflat is the lighter one; both use yt-dlp underneath. MeTube is the right tool when the workflow is "I have a link, save it", and the wrong one when it is "keep me up to date".

Small conveniences that add up

The queue survives a container restart if you mount STATE_DIR, so a batch of 40 lecture videos does not have to be re-pasted after an update. DEFAULT_THEME=dark saves a click. DELETE_FILE_ON_TRASHCAN=true makes the trash button in the UI actually remove the file rather than just the list entry, which is the behaviour most people expect. The project publishes a bookmarklet and there are community browser extensions that send the current tab to your instance, which turns saving a video into one click from wherever you found it. For the wider set of tools around this, the media server category and the YouTube alternatives page cover playback and front ends.

What I'd do

The Compose file above with a per-channel output template into a Jellyfin-scanned folder, cookies mounted, SponsorBlock enabled, STATE_DIR persisted, and Watchtower updating the image weekly. Behind Tailscale, not on the internet. Add Pinchflat the day you catch yourself pasting the same channel's links every week.