rgnet1/tidal-dl repository overview

⁠Tidal DL Pro

Tidal DL Pro is a browser-based TIDAL downloader. Run it in Docker, sign in to TIDAL once, then search, browse your library, and download from any device on your network.

A paid TIDAL subscription is required. Audio quality goes up to Hi-Res Lossless (24-bit / 192 kHz) when available.

⁠Features

• Search tracks, albums, artists, playlists, and videos — or paste a TIDAL URL
• Your TIDAL library — playlists, mixes, and favorites in the sidebar
• Download queue with live progress over WebSocket
• Settings for download engine, audio/video quality, lyrics, and FLAC extraction
• Dark / light mode

⁠Quick start (Docker Hub)

The published image is rgnet1/tidal-dl:latest⁠ on Docker Hub. You do not need to clone this repo or build anything locally.

⁠Option A — Docker Compose (recommended)

Create a folder for persistent data, download the compose file, and start:

mkdir -p tidal-dl-pro/config tidal-dl-pro/downloads
cd tidal-dl-pro

curl -fsSLO https://raw.githubusercontent.com/rgnet1/tidal-dl/master/docker-compose.yml

docker compose pull
docker compose up -d

Open http://localhost:8001⁠, click Login to TIDAL, complete OAuth, then search or browse your library.

To update to the latest image later:

docker compose pull && docker compose up -d

⁠Option B — docker pull and docker run

docker pull rgnet1/tidal-dl:latest

mkdir -p config downloads
docker run -d \
  --name tidal-dl-pro-web \
  -p 8001:8000 \
  -e PUID=1000 \
  -e PGID=1000 \
  -v "$(pwd)/config:/config" \
  -v "$(pwd)/downloads:/downloads" \
  --restart unless-stopped \
  rgnet1/tidal-dl:latest

Open http://localhost:8001⁠.

⁠Common commands

⁠Docker Compose file

The repo's docker-compose.yml pulls the published image — it does not build locally:

services:
  tidal-dl-pro-web:
    image: rgnet1/tidal-dl:latest   # pulled from Docker Hub
    pull_policy: always             # check for updates on every `docker compose up`
    container_name: tidal-dl-pro-web
    ports:
      - "${TIDAL_DL_PRO_PORT:-8001}:8000"
    environment:
      PUID: "${PUID:-1000}"
      PGID: "${PGID:-1000}"
    volumes:
      - ./config:/config
      - ./downloads:/downloads
    restart: unless-stopped

Image: rgnet1/tidal-dl:latest — always use the :latest tag unless you are pinning a specific version.

Port mapping: the app listens on port 8000 inside the container and is published on host port 8001 by default. Override with TIDAL_DL_PRO_PORT:

TIDAL_DL_PRO_PORT=8080 docker compose up -d

Volumes:

Both directories must exist (or are created with mkdir -p) before first run. Data survives docker compose down and image updates as long as these bind mounts stay in place.

Health check: Docker polls /api/status every 30 seconds. If the container is unhealthy, check logs with docker compose logs tidal-dl-pro-web.

⁠Configuration

Set these in a .env file next to docker-compose.yml, or export them in your shell:

On first boot the entrypoint remaps the container user to PUID:PGID and chowns /config. Your TIDAL OAuth token lives at ./config/tidal_dl_ng/token.json on the host.

⁠Web UI settings

Open the gear icon (top-right):

• Download engine — tidal-dl-ng (default; full library + mixes) or tiddl (experimental). Tokens are mirrored so you can switch without logging in again.
• Audio quality — Low up to Hi-Res Lossless (requires TIDAL HiFi Plus)
• Video quality — 360p–1080p
• Skip existing, download delay, and concurrency
• Metadata — embed lyrics, save .lrc files, FLAC extraction (FFmpeg is bundled in the image)

⁠API

Interactive docs: http://localhost:8001/docs⁠

⁠Troubleshooting

Port already in use

TIDAL_DL_PRO_PORT=8002 docker compose up -d

Wrong file ownership on ./config or ./downloads

PUID=$(id -u) PGID=$(id -g) docker compose up -d

Container won't start

docker compose logs tidal-dl-pro-web
docker compose pull && docker compose up -d

Pulling a stale image

Force Docker to fetch the latest from Hub:

docker compose pull --ignore-buildable
docker compose up -d

FLAC extraction failed

FFmpeg is included in the image. If extraction still fails, check the download logs in the web UI queue panel.

⁠Building locally (developers)

Only needed if you are modifying the source code. Clone the repo and use docker-compose.build.yml:

git clone https://github.com/rgnet1/tidal-dl.git
cd tidal-dl

mkdir -p config downloads
docker compose -f docker-compose.build.yml up -d --build

⁠Disclaimer

• For educational purposes only.
• Do not use this to distribute or pirate music.
• It may be illegal to use this application in your country.

⁠Credits

Built on tidal-dl-ng⁠ by @exislow.