Spotify Web API Python Library

1.0.270 verified Sat May 09 auth: no python

A modern, typed Python3 library for the Spotify Web API, supporting OAuth, pagination, and all major endpoints. Current version 1.0.270, released on PyPI with active development.

pip install spotifywebapipython

Common errors

error ModuleNotFoundError: No module named 'spotifywebapipython' ↓

cause Library not installed or installed in wrong environment.

fix

Run pip install spotifywebapipython in the correct Python environment (e.g., venv).

error TypeError: __init__() missing 3 required positional arguments: 'client_id', 'client_secret', 'redirect_uri' ↓

cause Using old instantiation pattern from version <1.0.0.

fix

Update code to SpotifyClient(client_id, client_secret, redirect_uri).

error spotifywebapipython.exceptions.SpotifyError: 401 - Unauthorized ↓

cause Invalid or expired access token; or missing scopes.

fix

Re-authenticate with proper scopes (e.g., client.authenticate(scopes=['user-library-read'])).

Warnings

breaking In version 1.0.0, the authentication flow changed from implicit grant to authorization code flow. The old `SpotifyClient(access_token=...)` pattern no longer works. ↓

fix Use `SpotifyClient(client_id, client_secret, redirect_uri)` and call `authenticate()`.

deprecated The `SpotifyClient.playlist()` method is deprecated in favor of `SpotifyClient.get_playlist()` as of v1.0.100. It will be removed in v2.0.0. ↓

fix Replace `client.playlist(id)` with `client.get_playlist(id)`.

gotcha When using the authorization code flow, the `redirect_uri` must exactly match the one registered in the Spotify Developer Dashboard, including trailing slashes. ↓

fix Use the exact URI string, e.g., 'http://localhost:8888/callback'.

Imports

SpotifyClient

from spotifywebapipython import SpotifyClient

Main client class.

SpotifyError

from spotifywebapipython import SpotifyError

Base exception class.

Quickstart

Initialize client, authenticate, and search for a track.

from spotifywebapipython import SpotifyClient

client = SpotifyClient(
    client_id=os.environ.get('SPOTIFY_CLIENT_ID', ''),
    client_secret=os.environ.get('SPOTIFY_CLIENT_SECRET', ''),
    redirect_uri=os.environ.get('SPOTIFY_REDIRECT_URI', '')
)
# Authenticate (requires user interaction for authorization code flow)
# For simplicity, use client credentials flow (no user-specific data):
client.authenticate()
# Search for a track
results = client.search('Never Gonna Give You Up', type='track')
print(results)