What is youtube-dl-nas?

A compact self-hosted download manager for NAS devices that wraps yt-dlp with a password-protected web interface. Users paste video, audio, or subtitle links into a queue that survives container restarts and avoids duplicate work. The dashboard shows live progress, lets you stop active transfers while keeping partial data, and can serve files already on disk. Mobile users send links straight from their phone share sheet via a PWA, an Android shortcut, or an iOS shortcut. Playlists and channels require an explicit scope choice before anything is queued. Subtitles can be checked against a reference transcript using nlptutti metrics. An MCP endpoint lets AI assistants propose batches of URLs for approval. Everything runs in one Docker image with nginx, the web app, and the MCP service sharing a single port; two bind mounts keep downloads and queue state persistent. The UI speaks English, Korean, Chinese, and Polish.

Should you self-host youtube-dl-nas?

youtube-dl-nas scores 50/100 on selfhost.directory (how scoring works) and ranks #27 of 45 in Download Management. It has 201 GitHub stars.

It shipped 10 stable releases in the past year. The latest, 26.1026, came out on 26 October 2026. New versions land roughly every 8 days.

Setup is moderate: expect some configuration beyond a single command. An official Docker image is available. It is MIT-licensed and written mostly in Python.

Its closest alternative on selfhost.directory is cobalt (83/100, 45 582 stars). It scores higher overall, so compare the two before you pick. See youtube-dl-nas vs cobalt side by side.

Features

Authenticated web dashboard
Duplicate Detection
MCP (Model Context Protocol) Support
Mounted file discovery
Playlist and channel scope guard
REST API
Restart-safe queue persistence
Smart Preflight with undo window
Subtitle quality analysis
Thumbnail sidecars
Topic collections
Video, audio, and subtitle downloads

How to configure youtube-dl-nas

CONFIG_DIR./configRecommended persistent state volume host path for queue, history, terms acceptance, and signed sessions.
Recommended persistent state volume host path for queue, history, terms acceptance, and signed sessions.
COOKIE_SECUREfalseSet to `true` when the dashboard is served exclusively over HTTPS.
Set to `true` when the dashboard is served exclusively over HTTPS.
DOWNLOAD_DIR./downloadsRequired persistent download volume host path.
Required persistent download volume host path.
MY_IDnas-userRequired login ID. Avoid values starting with `!`, `$`, or `&`.
Required login ID. Avoid values starting with `!`, `$`, or `&`.
MY_ID_FILEAdvanced alternative: read the login ID from one mounted secret file. `MY_ID` wins when both are set.
Advanced alternative: read the login ID from one mounted secret file. `MY_ID` wins when both are set.
MY_PWchange-this-passwordRequired login password. Avoid values starting with `!`, `$`, or `&`.
Required login password. Avoid values starting with `!`, `$`, or `&`.
MY_PW_FILEAdvanced alternative: read the login password from one mounted secret file. `MY_PW` wins when both are set.
Advanced alternative: read the login password from one mounted secret file. `MY_PW` wins when both are set.
NLPTUTTI_AUTO_UPDATEtrueInstall or upgrade `nlptutti` once whenever a new container starts. Defaults to `true`.
Install or upgrade `nlptutti` once whenever a new container starts. Defaults to `true`.
NLPTUTTI_UPDATE_TIMEOUT180Maximum runtime package-update duration in seconds. Defaults to `180`.
Maximum runtime package-update duration in seconds. Defaults to `180`.
PGID0Optional numeric owner for new download and state files. Defaults to `0`.
Optional numeric owner for new download and state files. Defaults to `0`.
PROXYOptional proxy value passed to `yt-dlp`. Defaults to empty.
Optional proxy value passed to `yt-dlp`. Defaults to empty.
PUID0Optional numeric owner for new download and state files. Defaults to `0`.
Optional numeric owner for new download and state files. Defaults to `0`.
TZAsia/SeoulOptional container time zone, for example `Asia/Seoul`.
Optional container time zone, for example `Asia/Seoul`.
UMASK022Optional file creation mask. Defaults to `022`.
Optional file creation mask. Defaults to `022`.
WEB_PORT8080Port forwarding. The app defaults to `8080`.
Port forwarding. The app defaults to `8080`.
YDLNAS_ALLOW_PRIVATE_SOURCESfalseAdvanced opt-in for downloads from private or local network addresses. Defaults to `false`.
Advanced opt-in for downloads from private or local network addresses. Defaults to `false`.
YDLNAS_API_TOKENOptional Bearer token for integrations. Normal ID/password API authentication remains available.
Optional Bearer token for integrations. Normal ID/password API authentication remains available.
YDLNAS_API_TOKEN_FILEAdvanced alternative: read the optional Bearer token from one mounted secret file. The direct variable wins when both are set.
Advanced alternative: read the optional Bearer token from one mounted secret file. The direct variable wins when both are set.
YDLNAS_MCP_BATCH_LIMIT25Maximum candidates per MCP or dashboard collection preview. Defaults to `25`, clamped to `1`–`100`.
Maximum candidates per MCP or dashboard collection preview. Defaults to `25`, clamped to `1`–`100`.
YDLNAS_STORAGE_CRITICAL_GB2Free-space threshold that pauses new queue additions. Defaults to `2`; set `0` to disable.
Free-space threshold that pauses new queue additions. Defaults to `2`; set `0` to disable.
YDLNAS_STORAGE_WARNING_GB10Free-space warning threshold in GiB. Defaults to `10`; set `0` to disable.
Free-space warning threshold in GiB. Defaults to `10`; set `0` to disable.
YTDLP_AUTO_UPDATEtrueKeep the startup and scheduled `yt-dlp` updater enabled. Defaults to `true`.
Keep the startup and scheduled `yt-dlp` updater enabled. Defaults to `true`.
YTDLP_COOKIES_FILEOptional path to a mounted Netscape-format cookies file.
Optional path to a mounted Netscape-format cookies file.
YTDLP_EXTRA_ARGSOptional administrator-controlled extra arguments parsed with shell-style quoting.
Optional administrator-controlled extra arguments parsed with shell-style quoting.
YTDLP_UPDATE_INTERVAL3600Updater interval in seconds. Defaults to `3600`, with a minimum of `300`.
Updater interval in seconds. Defaults to `3600`, with a minimum of `300`.