Spotify Downloader

Streaming is great for discovering and organizing music, but it does not give you ordinary audio files you can manage on your own. spotDL connects those two workflows.

A Spotify link supplies structured details - song title, artist, album, release date, track number and cover art. spotDL searches a supported provider for a suitable match, downloads the audio, converts it when needed and embeds the metadata. The result is a portable music collection, not a folder full of unidentified downloads.

Install with Python

Installing through Python is recommended for regular use, updates, automation and the complete command-line feature set. Requirements: Python 3.10-3.14, FFmpeg 4.2+, Deno recommended, and the Visual C++ Redistributable on Windows.

pip install spotdl

# update an existing install
pip install --upgrade spotdl

Docker

A maintained image suits servers, NAS systems and reproducible environments. The mounted music directory must be writable by the container user.

docker pull spotdl/spotify-downloader

docker run --rm -v $(pwd):/music \
  spotdl/spotify-downloader download [Spotify URL]

Termux, Arch & source builds

spotDL also installs on Android via Termux, through the Arch User Repository, or by building the executable from source with uv.

# Termux (Android)
curl -L https://raw.githubusercontent.com/spotDL/spotify-downloader/master/scripts/termux.sh | sh

# Build from source
git clone https://github.com/spotDL/spotify-downloader
cd spotify-downloader
pip install uv
uv sync
uv run scripts/build.py

FFmpeg

FFmpeg is required to process, convert and tag audio. Install it directly into the spotDL directory, or system-wide via your package manager.

spotdl --download-ffmpeg

# or system-wide
brew install ffmpeg            # macOS
sudo apt install ffmpeg        # Debian / Ubuntu

Deno

Deno is strongly recommended: current YouTube downloads through yt-dlp may require a JavaScript runtime. Without it, some tracks can fail, including certain videos marked as made for children.

spotdl --download-deno

Spotify authentication

Public links work for standard track, album, playlist, artist and search workflows. Accessing private account data - liked songs, personal playlists, followed artists, saved albums - requires Spotify authentication, and some shortcuts also need the official Spotify API option with valid credentials.

Choose a specific YouTube match

Automatic matching aims for the intended recording, but you can pair a specific YouTube source with Spotify metadata when you want exact control over the audio used.

spotdl download "https://www.youtube.com/watch?v=XXYlFuWEuKI|https://open.spotify.com/track/0VjIjW4GlUZAMYd2vXMi3b"

Download a personal Spotify library

Authenticated shortcuts can process liked songs, all your playlists, saved playlists, followed artists and saved albums. These require Spotify authentication; the current official-API workflow is intended for Spotify Premium accounts.

spotdl download saved --user-auth --use-official-api
spotdl download all-user-playlists --user-auth --use-official-api
spotdl download all-saved-playlists --user-auth --use-official-api
spotdl download all-user-followed-artists --user-auth --use-official-api
spotdl download all-user-saved-albums --user-auth --use-official-api

Auth flags include --user-auth, --use-official-api, --client-id, --client-secret, --auth-token, --cache-path, --no-cache, --headless and --max-retries. Treat credentials and tokens as private - never commit them to a public repository.

spotDL builds a search from Spotify details - title, artists, album, duration, release type - and evaluates candidate results, weighing whether a result is verified and watching for terms tied to live versions, remixes, covers and alternate recordings. It reduces the risk of grabbing an unrelated upload, but no matching system is perfect.

Control matching with --search-query (custom template), --dont-filter-results, --only-verified-results, --album-type, or a manual YouTubeURL|SpotifyURL pairing for an exact source.

spotDL downloads the audio available from the selected provider. It does not download Spotify's own streams, and it cannot create quality that is absent from the source. Standard YouTube sources generally provide up to 128 kbps; YouTube Music Premium users can reach 256 kbps with authenticated cookies and compatible M4A or Opus settings.

Choosing 320 kbps, FLAC or WAV does not turn a lower-bitrate source into higher quality - it only makes a larger file. For minimal processing, use M4A or Opus with conversion disabled; for maximum compatibility, use the default MP3.

# skip unnecessary conversion
spotdl download [URL] --format m4a --bitrate disable

# maximum compatibility
spotdl download [URL] --format mp3

Bitrate accepts constant rates from 8-320 kbps, variable levels 0-9, auto (match the source) or disable. With M4A and Opus, auto or disable can skip conversion when the source is already compatible.

Album artwork is embedded by default. For playlists, --playlist-numbering uses the playlist title and image as album/artwork, while --playlist-retain-track-cover keeps each track's own cover. Lyrics come from Genius, Musixmatch or AZLyrics in fallback order, and a synced provider can generate separate .lrc files.

spotdl download [query] --lyrics synced genius --generate-lrc

Control file and folder names

The default template is {artists} - {title}.{output-ext}. A custom template can define filenames, directories or both - producing a predictable library instead of a flat folder.

spotdl download [query] \
  --output "{artist}/{album}/{track-number} - {title}.{output-ext}"

Limit length with --max-filename-length and sanitize names for device compatibility with --restrict strict|ascii|none. The operating system may still enforce a shorter maximum path.

M3U playlists

Generate M3U or M3U8 files alongside the audio with --m3u, choose a name with --m3u "My Playlist.m3u8", or one file per list with --m3u "{list}". Record unavailable songs in M3U and archive files with --add-unavailable.

Duplicates & overwrite

Three overwrite modes - --overwrite skip (keep existing), --overwrite metadata (refresh tags, keep audio) and --overwrite force (re-download). Add --scan-for-songs to detect existing tracks, --archive to record completed downloads, and --create-skip-file / --respect-skip-file for idempotent batch jobs.

Filter the collection

Skip explicit tracks with --skip-explicit, ignore albums with --ignore-albums, fetch a song's albums with --fetch-albums, limit release type with --album-type single|album|compilation, accept only verified results with --only-verified-results, or disable filtering with --dont-filter-results.

Manage errors in large downloads

Long jobs can contain unavailable tracks, regional restrictions and provider failures. Print a summary with --print-errors or save it with --save-errors errors.txt, so you can process a large collection first and review exceptions afterward.

Advanced download controls

Tune throughput and behavior with --threads, --ffmpeg / --ffmpeg-args, --yt-dlp-args, --proxy http://host:port, --sponsor-block and --detect-formats. Custom tool arguments are intended for experienced users and can conflict with spotDL defaults.

Run the local Web UI

Start the browser interface with spotdl web. It is hosted locally - not on a remote conversion service - and is best for simple single-track downloads. Configure it with --host, --port (default 8800), --keep-alive, --allowed-origins and TLS options (--enable-tls, --cert-file, --key-file). Use --web-use-output-dir to follow your normal --output location.

Save configuration once

Generate a config file with spotdl --generate-config; it loads automatically on every run. It can store providers, formats, bitrate, output templates, FFmpeg/yt-dlp settings, threads, cookie files, proxy, overwrite rules, sync behavior and Web UI settings. Disable auto-loading with { "load_config": false }.

# default config locations
Windows:  C:\Users\<user>\.spotdl\config.json
Linux:    ~/.config/spotdl/config.json

Logging & diagnostics

Set verbosity with --log-level (CRITICAL → DEBUG, plus a MATCH level), simplify the terminal with --simple-tui, customize output with --log-format, profile with --profile, and see everything with spotdl --help.