Installation, operations, and mobile sharing guides for youtube-dl-nas
This is the operational path for a normal Docker or NAS installation. It keeps downloads and application state outside the container so an image update does not discard either one.
Docker Compose is the recommended deployment method.
git clone https://github.com/hyeonsangjeon/youtube-dl-nas.git
cd youtube-dl-nas
cp .env.example .env
Edit .env and set at least MY_ID and MY_PW. Review these paths before the
first start:
DOWNLOAD_DIR stores completed and partial media.CONFIG_DIR stores queue state, history, terms acceptance, and session data.WEB_PORT exposes the dashboard and defaults to 8080.Validate and start the deployment:
docker compose config
docker compose pull
docker compose up -d
docker compose ps
Open http://<nas-address>:<WEB_PORT> and sign in with the configured ID and
password. Use HTTPS before exposing the dashboard outside a trusted network.
For Compose secrets, mount one file per value and set MY_ID_FILE,
MY_PW_FILE, or YDLNAS_API_TOKEN_FILE to its container path. Direct
environment variables remain the default and take precedence when both forms
are configured. A requested secret file must be a readable, non-empty regular
file; startup errors identify only the variable and never print its contents.
Back up or snapshot DOWNLOAD_DIR and CONFIG_DIR before changing an image or
deployment configuration. Then update the checked-out deployment and recreate
the container:
git pull --ff-only
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 youtube-dl-nas
The default Compose file follows modenaf360/youtube-dl-nas:latest. To control
upgrade timing, replace latest in compose.yaml with a tag from the
release page and
run the same pull and up commands. Keep both persistent mounts unchanged.
Validate resolved settings and inspect recent logs:
docker compose config
docker compose ps
docker compose logs --tail=200 youtube-dl-nas
Confirm that MY_ID and MY_PW are set in .env and that another service is
not already using WEB_PORT.
Confirm the host paths behind /downfolder and /usr/src/app/metadata still
point to the intended persistent directories. The first mount holds media; the
second holds queue and history state. Recreating a container is safe only when
both mounts are preserved.
Inspect the mounted paths and available space:
docker compose exec youtube-dl-nas sh -lc \
'id; df -h /downfolder /usr/src/app/metadata; ls -ld /downfolder /usr/src/app/metadata'
If the directories are not writable, align PUID, PGID, and host-folder
permissions with the account that owns the mounted paths.
Pull the newest image first. The container also updates yt-dlp at startup and
on its configured schedule, but some sources can still require cookies, a
proxy, or a later upstream extractor fix. A signed-in administrator can manage
a bounded Netscape cookies file under dashboard Options. An external
YTDLP_COOKIES_FILE mount remains the read-only alternative. Check cookies,
PROXY, and YTDLP_EXTRA_ARGS only when the source requires them.
New requests accept only HTTP(S) sources that resolve to public-network
addresses. This prevents an exposed dashboard credential from turning the NAS
into a private-network fetcher. If the intended media source is hosted on a
trusted internal address, set YDLNAS_ALLOW_PRIVATE_SOURCES=true explicitly
and restrict dashboard access to trusted users.
Do not post private URLs, cookies, passwords, API tokens, or complete browser headers in logs or issues.
Use the full dashboard base URL, including the port and any reverse-proxy path.
Set COOKIE_SECURE=true only when the dashboard is served exclusively over
HTTPS. Mobile shares travel directly from the phone to the NAS; GitHub Pages
hosts only the setup guide and import files.
See the mobile sharing guide for Android PWA, Android local HTTP, and iPhone/iPad setup.
Search existing issues before opening a new report. If the problem remains, use the bug report form and include:
For feature ideas, use the feature request form.