MeTube
MeTube is a self-hosted web UI for yt-dlp, for downloading media from YouTube and dozens of other sites. Docker images are multi-arch (amd64/arm64).
Key capabilities:
- Download videos, audio, captions, and thumbnails from a browser UI.
- Download playlists and channels, with configurable output and download options.
- Subscribe to channels and playlists, periodically check for new items, and queue new uploads automatically.
🐳 Run using Docker
docker run -d -p 8081:8081 -v /path/to/downloads:/downloads ghcr.io/alexta69/metube
🐳 Run using Docker Compose
services:
metube:
image: ghcr.io/alexta69/metube
container_name: metube
restart: unless-stopped
ports:
- "8081:8081"
volumes:
- /path/to/downloads:/downloads
⚙️ Configuration via environment variables
Certain values can be set via environment variables, using the -e parameter on the docker command line, or the environment: section in Docker Compose.
🏠 Runtime & Permissions
- PUID: User under which MeTube will run. Defaults to
1000 (legacy UID also supported).
- PGID: Group under which MeTube will run. Defaults to
1000 (legacy GID also supported).
- UMASK: Umask value used by MeTube. Defaults to
022.
- DEFAULT_THEME: Default theme to use for the UI, can be set to
light, dark, or auto. Defaults to auto.
- LOGLEVEL: Log level, can be set to
DEBUG, INFO, WARNING, ERROR, CRITICAL, or NONE. Defaults to INFO.
- ENABLE_ACCESSLOG: Whether to enable access log. Defaults to
false.
⬇️ Download Behavior
- MAX_CONCURRENT_DOWNLOADS: Maximum number of simultaneous downloads allowed. For example, if set to
5, then at most five downloads will run concurrently, and any additional downloads will wait until one of the active downloads completes. Defaults to 3.
- DELETE_FILE_ON_TRASHCAN: if
true, downloaded files are deleted on the server, when they are trashed from the "Completed" section of the UI. Defaults to false.
- DEFAULT_OPTION_PLAYLIST_ITEM_LIMIT: Maximum number of playlist items that can be downloaded. Defaults to
0 (no limit).
- SUBSCRIPTION_DEFAULT_CHECK_INTERVAL: Default minutes between automatic checks for each subscription. Defaults to
60.
- SUBSCRIPTION_SCAN_PLAYLIST_END: Maximum playlist/channel entries to fetch per subscription check (newest-first). Defaults to
50.
- SUBSCRIPTION_MAX_SEEN_IDS: Cap on stored video IDs per subscription to limit state file growth. Defaults to
50000.
- CLEAR_COMPLETED_AFTER: Number of seconds after which completed (and failed) downloads are automatically removed from the "Completed" list. Defaults to
0 (disabled).
📁 Storage & Directories
- DOWNLOAD_DIR: Path to where the downloads will be saved. Defaults to
/downloads in the Docker image, and . otherwise.
- AUDIO_DOWNLOAD_DIR: Path to where audio-only downloads will be saved, if you wish to separate them from the video downloads. Defaults to the value of
DOWNLOAD_DIR.
- CUSTOM_DIRS: Whether to enable downloading videos into custom directories within the DOWNLOAD_DIR (or AUDIO_DOWNLOAD_DIR). When enabled, a Download Folder field appears under Advanced Options, where the directory for each download can be specified. Defaults to
true.
- CREATE_CUSTOM_DIRS: Whether to support automatically creating directories within the DOWNLOAD_DIR (or AUDIO_DOWNLOAD_DIR) if they do not exist. When enabled, the download directory selector supports free-text input, and the specified directory will be created recursively. Defaults to
true.
- CUSTOM_DIRS_EXCLUDE_REGEX: Regular expression to exclude some custom directories from the folder field's suggestions. Empty regex disables exclusion. Defaults to
(^|/)[.@].*$, which means directories starting with . or @.
- DEFAULT_FOLDER: Custom directory to pre-select in the download folder field, relative to DOWNLOAD_DIR (or AUDIO_DOWNLOAD_DIR), for when most downloads go to the same place. It is only a starting value — the field stays editable, so any other folder can still be picked per download. Requires CUSTOM_DIRS; ignored with a warning otherwise. Defaults to empty, i.e. the base download directory.
- DOWNLOAD_DIRS_INDEXABLE: If
true, the download directories (DOWNLOAD_DIR and AUDIO_DOWNLOAD_DIR) are indexable on the web server. Defaults to false.
- STATE_DIR: Path to where MeTube will store its persistent state files (
queue.json, pending.json, completed.json, subscriptions.json). Defaults to /downloads/.metube in the Docker image, and . otherwise.
- TEMP_DIR: Path where intermediary download files will be saved. Defaults to
/downloads in the Docker image, and . otherwise.
- Set this to an SSD or RAM filesystem (e.g.,
tmpfs) for better performance.
- Note: Using a RAM filesystem may prevent downloads from being resumed.
- CHOWN_DIRS: If
false, ownership of DOWNLOAD_DIR, STATE_DIR, and TEMP_DIR (and their contents) will not be set on container start. Ensure user under which MeTube runs has necessary access to these directories already. Defaults to true.
📝 File Naming & yt-dlp
- OUTPUT_TEMPLATE: The template for the filenames of the downloaded videos, formatted according to this spec. Defaults to
%(title)s.%(ext)s.
- OUTPUT_TEMPLATE_CHAPTER: The template for the filenames of the downloaded videos when split into chapters via postprocessors. Defaults to
%(title)s - %(section_number)s %(section_title)s.%(ext)s.
- OUTPUT_TEMPLATE_PLAYLIST: The template for the filenames of the downloaded videos when downloaded as a playlist. Defaults to
%(playlist_title)s/%(title)s.%(ext)s. Set to empty to use OUTPUT_TEMPLATE instead.
- OUTPUT_TEMPLATE_CHANNEL: The template for the filenames of the downloaded videos when downloaded as a channel. Defaults to
%(channel)s/%(title)s.%(ext)s. Set to empty to use OUTPUT_TEMPLATE instead.
- YTDL_OPTIONS: Additional options to pass to yt-dlp, as a JSON object. See Configuring yt-dlp options for details, examples, and available options reference.
- YTDL_OPTIONS_FILE: Path to a JSON file containing yt-dlp options. Monitored and reloaded automatically on changes. See Configuring yt-dlp options.
- YTDL_OPTIONS_PRESETS: Named bundles of yt-dlp options, selectable per download in the UI. See Configuring yt-dlp options for format and examples.
- YTDL_OPTIONS_PRESETS_FILE: Path to a JSON file containing presets. Monitored and reloaded automatically on changes. See Configuring yt-dlp options.
- ALLOW_YTDL_OPTIONS_OVERRIDES: Whether to show a free-text field in the UI for per-download yt-dlp option overrides. Defaults to
false. See Configuring yt-dlp options for details and security considerations.
- ALLOW_PRIVATE_ADDRESSES: Whether to allow downloads from private, loopback, link-local and other non-global addresses. Defaults to
false, which protects against SSRF by refusing URLs that resolve to internal hosts. Set to true only in trusted environments — for example when routing traffic through a proxy/VPN client in Fake-IP mode (sing-box, Clash, Mihomo), which resolves hosts to the 198.18.0.0/15 range. Enabling this disables the SSRF protection entirely, so only use it when you control the network. You do not need this to use a proxy on an internal address: a proxy configured through the proxy option in YTDL_OPTIONS (or the *_proxy environment variables) is always reachable at its own host and port, wherever it lives.
- YTDL_NIGHTLY_UPDATE_TIME: If set, will cause MeTube to use nightly yt-dlp builds instead of the stable releases. Set to the time (
HH:MM, 24-hour) when you want the daily upgrades and MeTube restart to happen. Defaults to empty (disabled).
A filename that would exceed the limit the filesystem accepts is shortened to fit, keeping its extension, with room left for the suffixes yt-dlp adds while downloading. Sites that put a long description in the title would otherwise fail the download outright with File name too long. Use trim_file_name in YTDL_OPTIONS if you want names shorter than the filesystem's own limit, or restrictfilenames to strip non-ASCII characters.
Enabling writeinfojson or writethumbnail in YTDL_OPTIONS also writes a feed-level .info.json and thumbnail when you add a playlist or channel. These reuse the template of the items they belong to — OUTPUT_TEMPLATE_CHANNEL or OUTPUT_TEMPLATE_PLAYLIST — evaluated against the feed itself, so with the defaults they land in the same folder as the videos, named after the feed. Set allow_playlist_files to false in YTDL_OPTIONS to skip them.
🌐 Web Server & URLs
- HOST: The host address the web server will bind to. Defaults to
0.0.0.0, which is every IPv4 interface but no IPv6 one. Set it to * (or leave it empty) to listen on both stacks, or to :: for IPv6 only — :: does not also accept IPv4, whatever the host's bindv6only setting says.
- PORT: The port number the web server will listen on. Defaults to
8081.
- URL_PREFIX: Base path for the web server (for use when hosting behind a reverse proxy). Defaults to
/.
- PUBLIC_HOST_URL: Base URL for the download links shown in the UI for completed files. By default, MeTube serves them under its own URL. If your download directory is accessible on another URL and you want the download links to be based there, use this variable to set it.
- PUBLIC_HOST_AUDIO_URL: Same as PUBLIC_HOST_URL but for audio downloads.
- HTTPS: Use
https instead of http (CERTFILE and KEYFILE required). Defaults to false.
- CERTFILE: HTTPS certificate file path.
- KEYFILE: HTTPS key file path.
- CORS_ALLOWED_ORIGINS: Comma-separated list of origins permitted to make cross-origin requests to the MeTube API;
* allows all. When unset or empty, all cross-origin requests are denied. Required for browser extensions and bookmarklets — see Sending links to MeTube. Naming origins explicitly also lets them send credentials (a login cookie, or the Authorization header a reverse proxy checks), which * deliberately does not: it would let any site you visit drive your instance with your own session.
- ROBOTS_TXT: A path to a
robots.txt file mounted in the container.
🎛️ Configuring yt-dlp options
MeTube lets you customize how yt-dlp behaves at three levels, from broadest to most specific:
- Global options — apply to every download by default.
- Presets — named bundles of options that users can pick per download from the UI.
- Per-download overrides — free-form options entered in the UI for a single download.
When a download starts, these layers are combined in order. If the same option appears in more than one layer, the more specific one wins: per-download overrides beat presets, and presets beat global options.
In JSON presets and overrides, setting an option to null clears that option for that download (for example, "download_archive": null overrides a global archive path so the archive is not used). This follows yt-dlp’s usual meaning of None for that option.
yt-dlp options in MeTube are expressed as JSON objects. The keys are yt-dlp API option names, which roughly correspond to command-line flags with dashes replaced by underscores. For example, the command-line flag --write-subs becomes "writesubtitles": true in JSON.
Tip: Some command-line flags don't have a direct single-key equivalent — for instance, --embed-thumbnail and --recode-video must be expressed via "postprocessors". A full list of available API options can be found in the yt-dlp source, and this conversion script can help translate command-line flags to their API equivalents.
Global options
Global options form the baseline for every download. There are two ways to define them, and you can use either or both:
Inline via environment variable (YTDL_OPTIONS) — pass a JSON object directly:
environment:
- 'YTDL_OPTIONS={"writesubtitles": true, "subtitleslangs": ["en", "de"], "updatetime": false, "writethumbnail": true}'
Via a JSON file (YTDL_OPTIONS_FILE) — mount a file into the container and point to it:
volumes:
- /path/to/ytdl-options.json:/config/ytdl-options.json
environment:
- YTDL_OPTIONS_FILE=/config/ytdl-options.json
where ytdl-options.json contains:
{
"writesubtitles": true,
"subtitleslangs": ["en", "de"],
"updatetime": false,
"writethumbnail": true
}
The file is monitored for changes and reloaded automatically — no container restart needed. If you use both methods and they define the same key, the file takes precedence.
Presets
Presets let you define named bundles of options that appear in the web UI under Advanced Options as "Option Presets". Users can select one or more presets per download, making it easy to apply common option combinations without editing global settings.
Like global options, presets can be set inline or via a file:
YTDL_OPTIONS_PRESETS — a JSON object where each key is a preset name and its value is a set of yt-dlp options.YTDL_OPTIONS_PRESETS_FILE — path to a JSON file containing presets, monitored and reloaded on changes.
If both are used and they define a preset with the same name, the file's version takes precedence.
Example — a presets file defining three presets:
{
"sponsorblock": {
"postprocessors": [
{ "key": "SponsorBlock", "categories": ["sponsor", "selfpromo", "interaction"] },
{ "key": "ModifyChapters", "remove_sponsor_segments": ["sponsor", "selfpromo", "interaction"] }
]
},
"embed-subs": {
"writesubtitles": true,
"writeautomaticsub": true,
"subtitleslangs": ["en", "de"],
"postprocessors": [{ "key": "FFmpegEmbedSubtitle" }]
},
"limit-rate": {
"ratelimit": 5000000
}
}
This makes three presets available in the UI:
- sponsorblock — strips sponsor, self-promo, and interaction segments from videos.
- embed-subs — downloads English and German subtitles and embeds them into the video file.
- limit-rate — caps download speed to ~5 MB/s.
When multiple presets are selected for a download, they are applied in order. If two presets set the same option, the later one wins.
Per-download overrides
For one-off tweaks, MeTube can expose a free-text JSON field in the UI ("Custom yt-dlp Options") where users type yt-dlp options that apply only to that single download. This is disabled by default:
environment:
- ALLOW_YTDL_OPTIONS_OVERRIDES=true
Once enabled, the field appears under Advanced Options. Any options entered there take the highest priority, overriding both global options and selected presets.
⚠️ Security note: Enabling this allows arbitrary yt-dlp API options to be supplied by anyone with access to the UI. Depending on the options used, this may enable arbitrary command execution inside the container. Enable only in trusted environments.
How the layers combine
When a download starts, the final set of yt-dlp options is built in this order:
- Start with global options (
YTDL_OPTIONS / YTDL_OPTIONS_FILE).
- Apply each selected preset in order (later presets overwrite earlier ones for conflicting keys).
- Apply any per-download overrides on top (overwrite everything else for conflicting keys).
MeTube always forces its own flat-extract behaviour during the initial metadata fetch (extract_flat, noplaylist, etc.); presets cannot override those keys for that phase.
Example: Suppose your global options set "writesubtitles": false, but you select a preset that sets "writesubtitles": true. Subtitles will be written for that download because the preset overrides the global setting. If you additionally enter {"writesubtitles": false} in the per-download overrides field, that value wins and subtitles will not be written.
Configuration cookbooks
The project's Wiki contains examples of useful configurations contributed by users of MeTube:
🍪 Using browser cookies
In case you need to use your browser's cookies with MeTube, for example to download restricted or private videos:
- Install in your browser an extension to extract cookies:
- Extract the cookies you need with the extension and save/export them as
cookies.txt.
- In MeTube, open Advanced Options and use the Upload Cookies button to upload the file.
- After upload, the cookie indicator should show as active.
- Use Delete Cookies in the same section to remove uploaded cookies.
🔗 Sending links to MeTube
Several integrations let you send URLs to MeTube from wherever you are, instead of pasting them into the UI. The browser-based ones make cross-origin requests, so they require CORS_ALLOWED_ORIGINS to be set; and if you're on an HTTPS page, your MeTube instance must be served over HTTPS too (with HTTPS=true or behind an HTTPS reverse proxy — see below).
Browser extensions allow right-clicking videos and sending them directly to MeTube. Since extensions request from their own origin, set CORS_ALLOWED_ORIGINS=*.
Bookmarklets send the currently open page to MeTube with one click. Add the origins of the sites where you use them to CORS_ALLOWED_ORIGINS, e.g. https://www.youtube.com,https://www.vimeo.com. If your instance sits behind authentication, list the origins individually rather than using * — only named origins are allowed to send credentials. The code (Chrome and Firefox variants, contributed by kushfest and shoonya75) is in the Bookmarklets wiki page.
iOS Shortcut: rithask created an iOS shortcut for sending URLs to MeTube from Safari's share menu; it prompts for your instance address on first use.
Raycast: dotvhs h
MeTube is a self-hosted web UI for yt-dlp, letting you download videos, audio, captions, and thumbnails from YouTube and dozens of other sites through a browser.