How to Use MeTube: A Beginner's Guide to Self-Hosted Video Downloads

CodexFuse Team · 2026-11-01T08:49:07.971Z · 16 min read

Learn how to use MeTube: install the self-hosted yt-dlp web UI with Docker, download your first video, set up presets and subscriptions, handle cookies, and hand files to Jellyfin.

Learning how to use MeTube takes about ten minutes: launch one Docker container, open the web interface, paste a video URL, pick a format, and press download. MeTube is a self-hosted web UI for yt-dlp — it turns the powerful but terminal-only downloader into a one-click interface that runs on your own server, keeps a queue and history, and can even watch channels for new uploads automatically. One important note before you start: "MeTube" is a crowded name. This guide is about the self-hosted one, alexta69/metube — the yt-dlp web interface. It is not the ad-free Android YouTube client (yashoncode's fork of NewTube/SmartTube), not the iOS "YouTube without the algorithm" app, and not the AI lecture-summarizer SaaS. The rest of this tutorial assumes the Docker project.

What Is MeTube?

MeTube is a self-hosted video downloader for YouTube and other sites, built as a web interface on top of yt-dlp. You run it in a Docker container on your own hardware, open its interface in a browser, and download videos through a queue instead of typing commands. Every download passes through yt-dlp under the hood, so it supports the same sites, formats, and quality options the command-line tool does. The project lives at github.com/alexta69/metube, where it has gathered more than 15,000 stars (GitHub API, checked this week) and ships a fresh Docker image with nearly every yt-dlp release. Because it runs on your own server with your own IP address, you — not a third-party site — control the downloads, the history, and the files. If you have never run a container before, our Docker beginner guide gets you to the one-command install in minutes.

How Do You Use MeTube? The 9-Step First-Run Arc

Using MeTube is a short arc: deploy it, open the interface, paste a link, and let the queue do the work. The whole thing, from zero to your first downloaded file, looks like this:

1. Run the container. One Docker command pulls the image and starts the server on port 8081.
2. Open the interface. Visit http://your-server-ip:8081 in a browser — no login screen, by design.
3. Point it at a download folder. Map a host directory to /downloads so files land on your disk, not inside the container.
4. Paste a video URL. YouTube, Vimeo, and hundreds of other sites work — paste into the Add box and press enter.
5. Pick a format. Choose best quality, a fixed resolution like 1080p, or audio-only MP3/AAC from the dropdown.
6. Queue it. The download joins the visible queue with a progress bar; up to three run at once by default.
7. Collect your file. Finished files appear in the download folder, named by the video title.
8. Set a preset. Save reusable option bundles (audio-only, subtitles-on) for one-click future downloads.
9. Subscribe to a channel. Tell MeTube to watch a channel or playlist and auto-queue new uploads.

Steps 1–3 take about five minutes; steps 4–7 are under a minute each. The remaining sections of this metube tutorial walk every step in detail, with the settings that matter and the gotchas that waste beginners' time.

What Do You Need Before You Start?

You need a machine that runs Docker — a home server, a NAS, or a VPS — plus a browser. Any 1-vCPU machine with 1 GB of RAM handles MeTube comfortably; the container image is around 280 MB and only works hard while a download is running. If the machine is a rented server, our what is VPS hosting explainer covers what you are actually buying. Docker itself is the only prerequisite: MeTube ships as a single container with yt-dlp and ffmpeg bundled, so there is nothing else to install. Make sure port 8081 is free on the host (or pick your own mapping), and decide where downloads should land — a folder like /home/you/media or your NAS media share, which matters later for the Jellyfin hand-off.

How Do You Install MeTube with Docker?

Install MeTube with one Docker command, using the current official MeTube Docker image from GitHub Container Registry. The project's README publishes every release to ghcr.io/alexta69/metube as a multi-architecture image (amd64 and arm64), and the older Docker Hub tag alexta69/metube is now the legacy one — always pull the GHCR image. Every step below is written as a MeTube self hosted guide: one container, one volume, one port.

docker run -d \
  --name metube \
  --restart unless-stopped \
  -p 8081:8081 \
  -v /path/to/downloads:/downloads \
  ghcr.io/alexta69/metube

Replace /path/to/downloads with your real folder, then open http://localhost:8081 (or your server's IP). For a long-lived setup, a compose file beats a raw command — it keeps the configuration in a file you can version and restart:

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

Choose your install path with this decision:

One version note: MeTube tags its releases by calendar date (this week's build is 2026.10.27, published with a yt-dlp bump from 2026.10.21 to 2026.10.26, per the project's releases page). Because a new image lands roughly every couple of days, pin a tag for stability or let watchtower roll you forward — running :latest without a strategy means surprise updates.

How Do You Download Your First Video?

Paste the video URL into the Add box at the top of the interface and choose a format before you press enter. The format dropdown is the most-used control in MeTube: "best video" merges the best video and audio streams into one file, fixed rungs like 1080p or 720p cap the size, and "audio only" extracts MP3 or AAC through ffmpeg — useful for lectures and podcasts. Behind the dropdown, MeTube translates your choice into yt-dlp format strings (best video becomes the familiar bestvideo+bestaudio/best selection), so anything yt-dlp can grab, MeTube can grab. Downloads join the queue with a live progress bar, and up to three run concurrently by default (MAX_CONCURRENT_DOWNLOADS). Finished files land in your mapped folder named %(title)s.%(ext)s — the video title plus its container. The history tab remembers everything you have ever downloaded, so a URL you queue twice shows up as a duplicate instead of downloading again.

How Do MeTube Presets Work?

Presets are named bundles of yt-dlp options you pick per download, so "audiobook mode" or "archive with subtitles" is one click instead of five settings. They sit in the middle of MeTube's three-layer option precedence, which is the single most important thing to understand about configuration: global options (YTDL_OPTIONS) apply to everything, presets override the globals when you select them under Advanced Options, and manual per-download overrides beat both — but only if you explicitly enable ALLOW_YTDL_OPTIONS_OVERRIDES. Two rules keep you safe: option keys use yt-dlp's API names, not its CLI flags (--write-subs becomes "writesubtitles": true), and setting a key to null in a preset or override clears it instead of erroring. Leave overrides disabled unless you fully trust everyone with browser access — a free-form option field can enable arbitrary command execution, which is why the default is off. The most useful presets to define first:

• Audiobook/lecture: audio-only extraction to MP3 at high bitrate, for podcasts and talks.
• Archive copy: best video plus embedded subtitles and the video description saved alongside.
• Quick preview: 720p, small enough to watch before deciding whether to keep the full quality.

Preset bundles can be entered as JSON in the environment (YTDL_OPTIONS_PRESETS) or loaded from a file (YTDL_OPTIONS_PRESETS_FILE); the file is watched and auto-reloaded, and it wins over the inline variable. Multiple presets apply in order, so "audiobook" plus "add-subtitles" composes instead of conflicting.

How Do MeTube Subscriptions Work?

Subscriptions make MeTube watch channels and playlists for you: it polls on a schedule and auto-queues anything new. Add a channel or playlist URL under Subscriptions, set a title regex if you only want matching uploads, and MeTube checks every 60 minutes by default (SUBSCRIPTION_DEFAULT_CHECK_INTERVAL) and queues new videos like any manual download. This is the feature that separates MeTube from one-off downloader UIs — subscribe once to a creator whose videos you archive, and your library grows itself. The subscription list, the download queue, and the history all live in the state directory (/downloads/.metube inside your mapped volume), so they survive container updates as long as you keep the same volume mapped. One caution for heavy archiving: each subscription check is a poll against the site, so dozens of subscriptions at short intervals can get rate-limited — the 60-minute default is sane for most people.

How Do You Download Playlists and Whole Channels?

Paste the playlist or channel URL into the same Add box you use for single videos — a MeTube playlist download works exactly like a single-video download: paste, pick a format, queue. MeTube detects collections and expands them into the queue. A playlist paste becomes one queue entry per video, each with the same format choice applied; a channel URL can be queued as a one-time snapshot of its videos, or — the better route for ongoing channels — added as a subscription so new uploads arrive automatically. For big archives, two settings matter: MAX_CONCURRENT_DOWNLOADS caps parallel downloads (the default of three keeps most home connections happy), and OUTPUT_TEMPLATE controls filenames — the playlist and channel variants let you prefix files with the playlist title or index so a 200-video playlist arrives in order instead of as a scrambled pile. If a playlist download stalls partway, the history tab shows exactly which videos are missing, and re-pasting the playlist URL skips what already downloaded.

How Do You Download Private or Age-Restricted Videos with Cookies?

Upload your browser cookies when a video demands a login: Advanced Options → Upload Cookies, and the status flips to "Cookies active". MeTube saves them as cookies.txt in the state directory and attaches them to every subsequent download, which unlocks private videos you can watch, age-restricted videos, and the "confirm you're not a bot" challenges that otherwise fail. The MeTube cookies flow has one gotcha that trips up beginners: there is no "read my browser automatically" option in the interface — you must export a cookies file from your browser (any standard cookies.txt exporter works) and upload it yourself, then replace the file when it expires. The uploaded file takes precedence over any cookiefile set in YTDL_OPTIONS, and the trash icon removes it when you no longer need it. Export cookies from a browser profile where you are logged in to the site, and remember that cookies are credentials — never share the exported file.

MeTube vs yt-dlp: Which One Should You Use?

MeTube IS yt-dlp wearing a web interface — so the choice is about how you work, not what engine you get. This one-page comparison settles it:

Most self-hosters end up with both: MeTube as the always-on appliance the household uses, and the yt-dlp command line — covered in our yt-dlp beginner guide — for the occasional exotic one-off that needs flags the UI never exposed. MeTube adds real value over the CLI in exactly three ways: the visible queue, the persistent history, and subscriptions. Everything else is the same engine.

How Do You Secure MeTube for Remote Access?

Put a reverse proxy with authentication in front of MeTube, because the app has no login of its own — and that is deliberate. The project's wiki answers "why no built-in authentication?" directly: MeTube ships zero user accounts on purpose, and expects HTTP basic auth, Authelia, or your proxy's equivalent at the edge (the reasoning is documented alongside issue #931). In practice that means never exposing port 8081 to the internet raw: terminate TLS on a reverse proxy and add its auth layer. Our Caddy beginner guide walks the reverse-proxy setup, and Caddy's basic_auth directive is a five-line addition. Two more house rules: keep the download volume and the state directory on a backed-up path (subscriptions and cookies live there), and only download videos you own or that are licensed for downloading — treat MeTube as an archiver for your own content, and respect each site's terms of service and copyright.

How Do You Hand Downloads Off to Jellyfin or Plex?

Point MeTube's download folder at the same directory your media server watches, and every download becomes watchable automatically. The hand-off is deliberately simple: MeTube downloads files, Jellyfin plays them — MeTube is the downloader lane, Jellyfin is the media-server lane, and the two never compete. Create a folder like /media/downloads inside your media library path, map it into MeTube as the download volume, and your server's library scan picks up each finished video. One naming tip: Jellyfin matches shows and movies by filename, so pair the download with a sensible OUTPUT_TEMPLATE (keep the video title, skip the random-looking video ID) and let your server organize from there. If you have not set up the media server yet, our Jellyfin beginner guide covers the library side of the same workflow.

What Are the Beginner Mistakes to Avoid?

Five mistakes account for most MeTube troubleshooting threads, and all five are preventable in the first five minutes:

• Losing the state directory on update. Queue, history, subscriptions, and cookies live in /downloads/.metube — if you map a fresh empty volume on each update, MeTube forgets everything. Keep the same volume across updates.
• Exposing port 8081 to the internet without auth. There is no login screen to protect you. Reverse proxy with basic auth or Authelia, or keep it on your LAN only.
• Letting the disk fill up. Subscriptions plus best-quality video is a disk-eating combination. Watch the volume and set a retention habit early.
• Ignoring the SSRF guard. MeTube blocks private-network URLs by default (ALLOW_PRIVATE_ADDRESSES is false) — pasting a localhost or LAN URL will fail until you understand and deliberately change that setting.
• Paste URL failures with no message. Age-gated or login-walled videos fail silently without cookies — the Upload Cookies step in the cookies section fixes the majority of these.

Sources

Every fact in this guide was verified on 2026-11-01 — making this MeTube tutorial current as of November 1, 2026: the MeTube repository (self-hosted video downloader for YouTube and other sites — web UI for yt-dlp; latest release tag 2026.10.27, released 2026-10-27 with a yt-dlp bump from 2026.10.21 to 2026.10.26; repository pushed 2026-10-27; the homonym landscape — yashoncode/metube Android client v3.1.1 released 2026-10-22, the metube.brrai.nz iOS/visionOS app, and the metube.io AI lecture-summarizer) at github.com/alexta69/metube and github.com/alexta69/metube/releases; the star and fork counts (15,151 stars, 1,132 forks) and the AGPL-3.0 license from the GitHub API; the README's quick-start (docker run -d -p 8081:8081 -v /path/to/downloads:/downloads ghcr.io/alexta69/metube; the compose structure with the ghcr.io/alexta69/metube image, metube container name, unless-stopped restart, and the 8081:8081 port mapping; the multi-arch amd64/arm64 builds; the environment-variable table — PORT default 8081, HOST default 0.0.0.0, PUID/PGID default 1000, UMASK 022, DOWNLOAD_DIR /downloads, AUDIO_DOWNLOAD_DIR defaulting to DOWNLOAD_DIR, TEMP_DIR, STATE_DIR /downloads/.metube holding the queue, history, subscriptions, and uploaded cookies, CUSTOM_DIRS, OUTPUT_TEMPLATE %(title)s.%(ext)s plus playlist/channel/chapter variants, MAX_CONCURRENT_DOWNLOADS 3, SUBSCRIPTION_DEFAULT_CHECK_INTERVAL 60 minutes, HTTPS/CERTFILE/KEYFILE, URL_PREFIX, ALLOW_PRIVATE_ADDRESSES default false, YTDL_OPTIONS and YTDL_OPTIONS_FILE with the file winning and being watched and auto-reloaded, YTDL_OPTIONS_PRESETS and YTDL_OPTIONS_PRESETS_FILE applying in order with the file winning, ALLOW_YTDL_OPTIONS_OVERRIDES default false with the arbitrary-command-execution warning, YTDL_NIGHTLY_UPDATE_TIME, and the watchtower recommendation since a new image ships with nearly every yt-dlp stable release) at github.com/alexta69/metube; the "Why no built-in authentication?" section (no login system by design, issue #931; use HTTP basic auth, Authelia, or your proxy's equivalent) on the wiki's reverse-proxy-configurations page at github.com/alexta69/metube/wiki/Reverse-proxy-configurations; the cookie upload flow (Advanced Options → Upload Cookies → "Cookies active"; cookies.txt saved in STATE_DIR and used for every download; Replace Cookies and trash-icon removal; no browser-reading UI — the uploaded file takes precedence over the cookiefile option in YTDL_OPTIONS) on the wiki's Using-browser-cookies page at github.com/alexta69/metube/wiki/Using-browser-cookies; the three-layer option precedence (Global YTDL_OPTIONS < Presets < Overrides; yt-dlp API option names such as "writesubtitles": true; null clears a key) on the wiki's yt-dlp-options page at github.com/alexta69/metube/wiki/yt-dlp-options; the subscription feature (auto-queue new uploads from channels and playlists on a poll interval, optional title regex) in the README and the wiki's Subscriptions page; the format-dropdown quality mapping ("best video", "1080p", "720p", "480p", "audio only"; MP3/AAC extraction via ffmpeg; translation to yt-dlp format strings like bestvideo+bestaudio/best) per selfhostedguides.com's MeTube guide and a deepwiki.com code analysis of the repository (secondary sources — exact dropdown labels not verified against the raw source). The install-path decision table, the MeTube-vs-yt-dlp comparison, and the quality-to-use-case framing are original syntheses for this guide.

Frequently Asked Questions

Is MeTube free?

Yes. MeTube is open-source software under the AGPL-3.0 license, and the Docker image costs nothing — you pull it from GitHub Container Registry and run it on your own hardware. The only real cost is the machine it runs on: a home server you already own, or a small VPS. There is no premium tier and no account to create.

Is it legal to download videos with MeTube?

That depends on what you download, not on the tool. MeTube itself is a neutral downloader, like a browser's save button. Downloading your own uploads, Creative Commons or public-domain videos, and content the uploader explicitly offers for download is fine; ripping copyrighted material you do not own can violate both the site's terms of service and copyright law. Treat MeTube as an archiver for your own content.

Why is there no login on MeTube?

It is a deliberate design choice, not a missing feature. The project maintains no user accounts on purpose — authentication belongs at your reverse proxy (HTTP basic auth, Authelia, or similar), not inside the downloader. That is also why you should never expose MeTube's port directly to the internet without that proxy layer in front of it.

Why do some videos fail with "sign in to confirm" errors?

Those videos need proof you are logged in — age-restricted content, private videos, and the "confirm you're not a bot" challenges all require cookies. Go to Advanced Options, upload a cookies.txt exported from a browser where you are signed in, and the status changes to "Cookies active". The uploaded file then applies to every download until you replace or remove it.

Should I use MeTube or just yt-dlp?

Use MeTube when the downloader lives on a server: the visible queue, persistent history, and channel subscriptions are the whole point, and anyone in the household can use a browser instead of a terminal. Use the yt-dlp command line for one-off downloads and for exotic flags the UI never exposed. Many self-hosters run both — MeTube as the always-on appliance, yt-dlp for the occasional special case.