spotizerr-dev/docs/user/getting-started.md

Getting started

Prerequisites

• Docker and Docker Compose
• Spotify account(s)
• Deezer account (optional, recommended for FLAC)
• Spotify API client_id and client_secret (from Spotify Developer Dashboard)

Quick start (Docker Compose):

mkdir spotizerr && cd spotizerr
mkdir -p data logs downloads && touch .cache
wget https://github.com/spotizerr-dev/spotizerr/blob/main/docker-compose.yaml

# Before running this last command, check your docker compose file first, it is well-documented.
docker compose up -d

Initial setup

• Open the web UI (default: http://localhost:7171)
• Go to Configuration → Accounts
• Use spotizerr-auth to register Spotify credentials quickly

Spotify account setup with spotizerr-auth:

docker run --network=host --rm -it cooldockerizer93/spotizerr-auth

or, if docker doesn't work:

Alternative installers

Linux / macOS

python3 -m venv .venv && source .venv/bin/activate && pip install spotizerr-auth

Windows (PowerShell)

python -m venv .venv; .venv\Scripts\Activate.ps1; pip install spotizerr-auth

Windows (cmd.exe)

python -m venv .venv && .venv\Scripts\activate && pip install spotizerr-auth

Then run spotizerr-auth.

Note: You will have to enable the virtual environment everytime you want to register a new account.

Registering account

• Ensure Spotify client is opened before starting
• Enter Spotizerr URL (e.g., http://localhost:7171)
• Enter Spotify API client_id and client_secret if prompted (one-time)
• Name the account + region code (e.g., US)
• Transfer playback to the temporary device when asked
• Credentials are posted to Spotizerr automatically

Next steps

• Add Deezer ARL in Configuration → Accounts (optional, allows for FLAC availability if premium)
• Adjust Download and Formatting options
• Enable Watch system if you want automatic downloads

Troubleshooting (quick)

• Downloads not starting: verify service credentials and API keys
• Watch not working: enable in Configuration → Watch and set intervals
• Auth issues: ensure JWT secret and SSO creds (if used); try clearing browser cache
• Queue stalling: force-refresh the page (ctrl+F5)

Logs

docker logs spotizerr

• Enable Watch system if you want auto-downloads