Configuration

MeTube is configured entirely through environment variables. These can be set using the -e flag in a docker run command or under the environment: section in a docker-compose.yml file.

Core Configuration

These variables control fundamental aspects of MeTube's operation, such as file paths and user permissions.

Variable	Description	Default	Example
UID	The User ID under which MeTube will run. This is used to set file permissions on downloaded content.	1000	-e UID=1001
GID	The Group ID under which MeTube will run.	1000	-e GID=1001
UMASK	The umask value used by MeTube for file and directory creation.	022	-e UMASK=002
URL_PREFIX	The base path for the web server, useful when hosting behind a reverse proxy under a subfolder. Must end with a /.	/	-e URL_PREFIX=/metube/

Directory Configuration

These variables define where files are stored.

Variable	Description	Default	Example
DOWNLOAD_DIR	The primary directory inside the container for saving video downloads.	/downloads	volumes: - ./videos:/downloads
AUDIO_DOWNLOAD_DIR	A separate directory for audio-only downloads. If not set, it uses the DOWNLOAD_DIR.	DOWNLOAD_DIR	volumes: - ./audio:/audio -e AUDIO_DOWNLOAD_DIR=/audio
STATE_DIR	The directory for storing queue and history persistence files.	/downloads/.metube	-e STATE_DIR=/config
TEMP_DIR	The directory for temporary files during download. For better performance, consider mapping this to an SSD or a RAM filesystem (tmpfs).	/downloads	tmpfs: /tmpfs -e TEMP_DIR=/tmpfs

Feature Configuration

These variables enable or disable specific features within the MeTube UI and backend.

Variable	Description	Default	Example
CUSTOM_DIRS	If true, enables downloading into custom subdirectories within the main download directories.	true	-e CUSTOM_DIRS=false
CREATE_CUSTOM_DIRS	If true, allows users to type new folder names in the UI, which will be created automatically.	true	-e CREATE_CUSTOM_DIRS=false
CUSTOM_DIRS_EXCLUDE_REGEX	A regular expression to exclude certain directories from appearing in the download folder dropdown.	(^|/)[.@].*$	-e CUSTOM_DIRS_EXCLUDE_REGEX=''
DELETE_FILE_ON_TRASHCAN	If true, deleting an item from the 'Completed' list will also delete the corresponding file from the server.	false	-e DELETE_FILE_ON_TRASHCAN=true
DOWNLOAD_DIRS_INDEXABLE	If true, allows directory listings for the download directories, making files browsable at /download/ and /audio_download/.	false	-e DOWNLOAD_DIRS_INDEXABLE=true

Download Behavior

Control how downloads are processed and named.

Variable	Description	Default	Example
DOWNLOAD_MODE	Controls download scheduling. Options: sequential (one at a time), concurrent (unlimited), limited (capped by MAX_CONCURRENT_DOWNLOADS).	limited	-e DOWNLOAD_MODE=sequential
MAX_CONCURRENT_DOWNLOADS	When DOWNLOAD_MODE is limited, this sets the maximum number of simultaneous downloads.	3	-e MAX_CONCURRENT_DOWNLOADS=5
OUTPUT_TEMPLATE	The filename template for single video downloads. See the yt-dlp documentation for syntax.	%(title)s.%(ext)s	-e OUTPUT_TEMPLATE='%(uploader)s - %(title)s.%(ext)s'
OUTPUT_TEMPLATE_CHAPTER	Filename template for videos split into chapters.	%(title)s - %(section_number)s %(section_title)s.%(ext)s	See default
OUTPUT_TEMPLATE_PLAYLIST	Filename template for videos downloaded as part of a playlist.	%(playlist_title)s/%(title)s.%(ext)s	-e OUTPUT_TEMPLATE_PLAYLIST='%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s'
DEFAULT_THEME	The default UI theme. Options: light, dark, auto.	auto	-e DEFAULT_THEME=dark
DEFAULT_OPTION_PLAYLIST_STRICT_MODE	If true, the "Strict Playlist mode" switch is enabled by default.	false	-e DEFAULT_OPTION_PLAYLIST_STRICT_MODE=true
DEFAULT_OPTION_PLAYLIST_ITEM_LIMIT	Default maximum number of playlist items to download. 0 means no limit.	0	-e DEFAULT_OPTION_PLAYLIST_ITEM_LIMIT=10

Advanced yt-dlp Configuration

These variables allow you to pass advanced options directly to the yt-dlp engine.

Variable	Description	Default	Example
YTDL_OPTIONS	A JSON string of additional options to pass to yt-dlp. See the yt-dlp options documentation for available keys.	{}	-e YTDL_OPTIONS='{"continuedl": true, "--sponskrub-force": true}'
YTDL_OPTIONS_FILE	A path to a JSON file (inside the container) containing yt-dlp options. Options from YTDL_OPTIONS will override options from this file.	''	-e YTDL_OPTIONS_FILE=/config/ytdl_options.json

For examples and common use cases, check out the community-contributed YTDL_OPTIONS Cookbook.

Using Browser Cookies

To download private or members-only content, you may need to provide browser cookies.

1. Map a volume for your cookies file:

   volumes:
     - /path/to/cookies:/cookies

2. Set the cookiefile option in YTDL_OPTIONS:

   environment:
     - YTDL_OPTIONS={"cookiefile":"/cookies/cookies.txt"}

3. Use a browser extension to export your cookies, save the file as cookies.txt in your mapped volume, and restart the container.

Network Configuration

Variable	Description	Default	Example
PUBLIC_HOST_URL	The base URL used for generating download links in the UI for completed video files.	(MeTube's own URL)	-e PUBLIC_HOST_URL=https://downloads.example.com/videos/
PUBLIC_HOST_AUDIO_URL	Same as PUBLIC_HOST_URL, but for audio downloads.	(MeTube's own URL)	-e PUBLIC_HOST_AUDIO_URL=https://downloads.example.com/audio/
HTTPS	If true, enables native HTTPS mode. Requires CERTFILE and KEYFILE to be set.	false	-e HTTPS=true
CERTFILE	Path to the HTTPS certificate file inside the container.	''	-e CERTFILE=/ssl/cert.pem
KEYFILE	Path to the HTTPS private key file inside the container.	''	-e KEYFILE=/ssl/key.pem

System & Logging

Variable	Description	Default	Example
LOGLEVEL	The logging level. Options: DEBUG, INFO, WARNING, ERROR, CRITICAL, NONE.	INFO	-e LOGLEVEL=DEBUG
ENABLE_ACCESSLOG	If true, enables aiohttp's access log.	false	-e ENABLE_ACCESSLOG=true
ROBOTS_TXT	Path to a custom robots.txt file to be served.	''	-e ROBOTS_TXT=/config/robots.txt