spotDL - Spotify Downloader

4.4.4 verified Fri May 01 auth: no python

spotDL downloads Spotify playlists and songs with album art and metadata. Version 4.4.4 requires Python <3.15,>=3.10. It uses yt-dlp or other sources to fetch audio. Releases are irregular but frequent.

pip install spotdl

Common errors

error ModuleNotFoundError: No module named 'spotdl' ↓

cause spotdl is not installed or not found in the current Python environment.

fix

Run 'pip install spotdl' in the correct environment. Ensure you are using the same Python interpreter that spotdl was installed in.

error spotdl: error: unrecognized arguments: --format ↓

cause The '--format' flag was removed in v4.x; the output format is now specified via '--output'.

fix

Use '--output' with placeholders like '{artist} - {title}.{ext}'.

error No module named 'yt_dlp' ↓

cause yt-dlp is not installed.

fix

Run 'pip install yt-dlp'.

error ffmpeg not found. Please install ffmpeg. ↓

cause ffmpeg is not installed on the system PATH.

fix

Install ffmpeg: on Ubuntu/Debian 'sudo apt install ffmpeg', on macOS 'brew install ffmpeg', on Windows download from ffmpeg.org.

error spotify token expired or invalid ↓

cause OAuth token is stale or credentials are missing.

fix

Re-authenticate by running 'spotdl --auth' or set SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET environment variables.

Warnings

breaking In version 4.x, the CLI and API were restructured. Old imports like 'from spotdl import download' no longer work. ↓

fix Use 'from spotdl import SpotDL' and instantiate the class.

gotcha ffmpeg must be installed separately on your system. Without it, spotdl will fail silently or produce corrupted files. ↓

fix Install ffmpeg via your package manager (e.g., 'sudo apt install ffmpeg' on Ubuntu, 'brew install ffmpeg' on macOS).

deprecated The old '--write-m3u' flag is deprecated and may be removed in future versions. ↓

fix Use '--save-file' with appropriate format instead.

gotcha Spotify API requires valid OAuth credentials. Without setting SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET, downloads will fail with 401 errors. ↓

fix Set environment variables: export SPOTIFY_CLIENT_ID='your_id'; export SPOTIFY_CLIENT_SECRET='your_secret'.

Imports

SpotDL
```
from spotdl import SpotDL
```
Main class for programmatic use.
__main__
wrong
```
spotdl (without module invocation)
```
correct
```
python -m spotdl
```
Running directly as 'spotdl' may not work if not installed in PATH; use 'python -m spotdl'.

Quickstart

Download a single track by URL. Ensure Spotify credentials are set via environment variables SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET, or use OAuth.

python -m spotdl 'https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT' --output '{artist} - {title}.{ext}'