Skip to content

Getting Started

This guide walks you from zero to a running container.

Prerequisites

You will create Spotify credentials and a tracking.yaml file in the next steps.

1) Create Spotify credentials

Spotify Downloader uses Spotify client credentials to read artist and playlist data. You need a Client ID and Client Secret so the app can call the Spotify API.

Go to the Spotify Developer Dashboard and create an app:

https://developer.spotify.com/dashboard

Copy the Client ID and Client Secret. These values go into CLIENT__ID and CLIENT__SECRET in your compose file.

Note: client credentials only allow access to public playlists.

Spotify Developer policy changes (March 9, 2026)

Spotify now requires the app owner to have an active Spotify Premium subscription for Development Mode Web API access. If the app owner does not have Premium, this project may stop working.

Spotify also introduced stricter Development Mode limits (for example, fewer supported endpoints/fields, one Client ID per developer, and up to five authorized users). These limits can affect functionality depending on your setup.

See the full discussion in #51.

2) Create a tracking file

Create a tracking.yaml file on your host:

artists:
  - name: Dua Lipa
    url: https://open.spotify.com/artist/6M2wZ9GZgrQXHCFfjv46we
  - name: The Beatles
    url: https://open.spotify.com/artist/3WrFJ7ztbogyGnTHbHJFl2
    refresh: false

playlists:
  - name: Chill Mix
    url: https://open.spotify.com/playlist/37i9dQZF1DWXRqgorJj26U
    mode: full

See the full format and options in tracking.yaml.

3) Run with Docker Compose

Use a compose file like this:

name: spotify-downloader

services:
  spotify-downloader:
    image: pjmeca/spotify-downloader:latest
    container_name: spotify-downloader
    restart: unless-stopped
    volumes:
      - /your/main/music/path:/music
      - /path/to/tracking.yaml:/app/tracking.yaml:ro
      - /path/to/cache:/app/cache
      - /path/to/logs:/app/logs
    environment:
      CRON_SCHEDULE: "0 0 * * *"
      CLIENT__ID: "your_spotify_client_id"
      CLIENT__SECRET: "your_spotify_client_secret"
      TZ: Europe/Madrid
      FORMAT: "opus"
      OPTIONS: ""
      YT_DLP_UPDATE_POLICY: "before-run"

Then start the container:

docker compose up -d

If you want to build the image locally instead of pulling from Docker Hub, see Advanced.