Spotify Web Downloader

1.8.1 verified Sat May 09 auth: no python

A Python CLI application for downloading songs and music videos from Spotify by analyzing Spotify URLs, fetching metadata, and sourcing audio/video from YouTube or other providers. Version 1.8.1, requires Python >=3.8. Active maintenance.

pip install spotify-web-downloader

Common errors

error ModuleNotFoundError: No module named 'spotify_web_downloader' ↓

cause Package not installed or imported with wrong name (hyphen vs underscore).

fix

Install with pip install spotify-web-downloader and import using underscores: from spotify_web_downloader import SpotifyDownloader.

error spotify_web_downloader.exceptions.AuthenticationError: Invalid credentials ↓

cause Spotify cookies expired or not provided correctly.

fix

Ensure valid sp_dc and sp_key cookies are set via environment variables or config file. See https://github.com/spotify/spotify-web-downloader#authentication

Warnings

gotcha The library may violate Spotify's Terms of Service as it bypasses official APIs. Use at your own risk; accounts can be banned. ↓

fix Consider using Spotify's official API and a legal streaming source.

breaking Version 1.8.0 removed the `--no-ytm` flag in favor of a config file. Scripts using the old flag will fail. ↓

fix Remove the `--no-ytm` argument and configure via `~/.config/spotify-web-downloader/config.json`.

Imports

SpotifyDownloader

wrong

from spotify_web_downloader.SpotifyDownloader import SpotifyDownloader

correct

from spotify_web_downloader import SpotifyDownloader

Wrong path leads to ModuleNotFoundError, correct import uses lowercase module name.

Quickstart

Initialize the downloader, provide a Spotify track URL, and download the audio.

from spotify_web_downloader import SpotifyDownloader

downloader = SpotifyDownloader()

track_url = "https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT"
result = downloader.download_track(track_url)
print(f"Downloaded: {result['title']} by {result['artist']}")