spotdl

library4.5.0pypypi✓ verified 80d ago

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.

data serialization

pip install spotdl

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · SPOTDL

spotdl

datapythonv4.5.0

Install

14.5s avg

Import

—

Disk

182MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 189.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 14.5s · import 0.000s · 186MB

182MB installed

● package 182MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Spotdl

✓ from spotdl import Spotdl

✗ from spotdl import SpotDL

Downloader

✓ from spotdl import Downloader

Song

✓ from spotdl import Song

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}'

spotdl --version

Debug

Known issues

breakingIn 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.

affects: >=4.0.0

gotchaffmpeg 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).

affects: all

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

fix

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

affects: >=4.2.0

gotchaSpotify 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'.

affects: all

Upgrade

Version history

4.5.0latest on PyPI · released May 16, 2026

Audit

Dependencies

ffmpegrequiredRequired for audio processing; must be installed separately (not pip).

yt-dlprequiredUsed as the default downloader for audio extraction from YouTube.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/spotDL/spotify-downloader ↗

packagehttps://pypi.org/project/spotdl/ ↗

docshttps://spotdl.rtfd.io/en/latest/ ↗