spotDL Manual

spotDL is a free, open-source command-line tool. Importantly, it does not rip protected audio out of Spotify itself. It uses your Spotify link only to read the song's metadata (title, artist, album, cover art), then downloads a matching audio track from YouTube Music and tags it. That distinction matters for both audio quality and the legal notes at the bottom of this page.

spotDL is a Python command-line program. The cleanest install path is pipx, which puts spotDL in its own isolated environment so it never collides with your other Python packages. Follow the steps for your operating system. You need FFmpeg too — spotDL uses it to convert audio.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew install ffmpeg pipx
pipx ensurepath
pipx install spotdl

winget install Python.Python.3.12
winget install Gyan.FFmpeg
pip install spotdl

sudo apt update && sudo apt install -y python3 python3-pip pipx ffmpeg
pipx ensurepath
pipx install spotdl

spotdl --download-ffmpeg

spotdl --version

Not comfortable with a terminal? Hand this entire prompt to an AI coding assistant that can run commands on your computer (see the note below for what that means). It will install spotDL for you, check that it works, and — if it turns out it can't run commands — explain in plain English exactly what you need instead.

I want to install and use spotDL, the open-source Spotify downloader, on my computer. Please help me end to end.

FIRST, check your own capabilities: can you actually run shell/terminal commands on my computer right now (for example, do you have a Bash, shell, or command-execution tool)?

IF YES — you can run commands:
1. Detect my operating system (macOS, Windows, or Linux).
2. Check whether Python 3.9+, FFmpeg, and pipx are installed; install whatever is missing using the correct package manager for my OS (Homebrew on macOS, winget on Windows, apt/dnf/pacman on Linux).
3. Install spotDL with: pipx install spotdl  (or: pip install spotdl  if pipx is unavailable).
4. Verify the install by running: spotdl --version
5. Show me one example command to download a song, and offer to run a test download on a royalty-free or public-domain track to confirm everything works.
Explain each step in plain language as you go, and stop and ask me before doing anything that needs my confirmation.

IF NO — you cannot run commands on my computer (you can only chat):
Do NOT pretend to install anything. Instead, tell me clearly:
1. That spotDL is a command-line program, so it must be installed and run by something that has real access to my computer's terminal — a chat-only AI cannot do it.
2. That I have two good options: (a) open the Terminal app (macOS/Linux) or PowerShell (Windows) myself and paste in commands you give me, or (b) use an AI assistant that has terminal/command-line access — for example Claude Code, Cursor, or a similar coding agent running on my own machine.
3. Briefly, why this is: installing software, downloading files, and running spotDL all happen on my computer's operating system, which a website-based chat AI is sandboxed away from for security. An AI with terminal access is allowed to run those commands directly.
Then, give me the exact copy-paste commands for my operating system so I can run them myself in the Terminal, and walk me through them one at a time.

The core command is spotdl download (or just spotdl followed by a link — download is the default operation). Wrap every URL in quotes so your shell doesn't choke on special characters.

spotdl "https://open.spotify.com/track/..."

spotdl download "https://open.spotify.com/album/..."

spotdl download "https://open.spotify.com/playlist/..."

spotdl download "https://open.spotify.com/artist/..."

spotdl download "Fleetwood Mac - Dreams"

spotdl download "URL_one" "URL_two" "URL_three"

Beyond download, spotDL has several other operations. The pattern is always spotdl <operation> <query>.

spotdl save "PLAYLIST_URL" --save-file my_list.spotdl

spotdl download my_list.spotdl

spotdl url "TRACK_URL"

spotdl web

Choose your audio format and bitrate. A note on "quality": spotDL's source is YouTube Music, which is lossy. Exporting to FLAC does not create true lossless audio from a lossy source — it just rewraps it. Use FLAC only if a downstream tool requires it; otherwise MP3 320k or the default is best.

spotdl download "URL" --format flac

spotdl download "URL" --bitrate 320k

spotdl download "URL" --bitrate disable

spotdl download "PLAYLIST_URL" --threads 8

The --output flag controls where files go and how they're named, using template variables in curly braces. Build the folder structure you want automatically.

spotdl download "URL" --output "{artist}/{album}/{track-number} - {title}.{output-ext}"

spotdl download "URL" --output "~/Music/{artist} - {title}.{output-ext}"

spotdl download "PLAYLIST_URL" --output "{playlist}/{artist} - {title}.{output-ext}"

spotdl download "PLAYLIST_URL" --overwrite skip

spotDL embeds tags, album art, and lyrics automatically. These flags let you fine-tune the sources and fix tags on files you already downloaded.

spotdl download "URL" --lyrics genius musixmatch

spotdl meta "PLAYLIST_URL" --output "~/Music"

spotdl download "URL" --generate-lrc

spotdl download "URL" --skip-album-art

sync keeps a local folder in lockstep with a Spotify playlist. The first run creates a sync file; later runs add tracks added to the playlist and delete tracks removed from it. Perfect for a cron job or a "keep my library current" workflow.

spotdl sync "PLAYLIST_URL" --save-file playlist.sync.spotdl

spotdl sync playlist.sync.spotdl

Save your favorite flags once in a config file so you never retype them, and keep spotDL current.

spotdl --generate-config

spotdl download "URL" --config

spotdl download "saved" --user-auth

# installed with pipx:
pipx upgrade spotdl
# installed with pip:
pip install --upgrade spotdl

The most common snags and their fixes.

pipx ensurepath
# then close and reopen your terminal

spotdl --download-ffmpeg

spotdl download "URL" --audio youtube-music --only-verified-results

pipx upgrade spotdl
spotdl download "URL" --threads 1

spotdl --help

A short, honest note so you can make informed choices.