Install & Compatibility
Where this runs
tested against v2.26.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
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 1.030s · 26MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 2.5s · import 0.897s · 27MB
24MB installed
● package 24MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Spotify
✓ from spotipy import Spotify
SpotifyClientCredentials
✓ from spotipy.oauth2 import SpotifyClientCredentials
SpotifyOAuth
✓ from spotipy.oauth2 import SpotifyOAuth
util.prompt_for_user_token
✓ from spotipy import util
✗ from spotipy.oauth2 import util.prompt_for_user_token
While `spotipy.util` contains `prompt_for_user_token`, the recommended approach for user authentication is via `SpotifyOAuth` directly passed to the `Spotify` constructor, or using `SpotifyOAuth`'s methods. Direct import from `spotipy.oauth2` is incorrect as `util` is at the `spotipy` module level.
This quickstart demonstrates how to use Spotipy with the Client Credentials Flow for server-to-server authentication, allowing access to public Spotify data without user interaction. It retrieves artist information and their albums. Ensure you have your Spotify API Client ID and Client Secret set as environment variables or replace the placeholders.
import os
from spotipy import Spotify
from spotipy.oauth2 import SpotifyClientCredentials
# Set your Spotify API credentials as environment variables
# SPOTIPY_CLIENT_ID='your_client_id'
# SPOTIPY_CLIENT_SECRET='your_client_secret'
client_id = os.environ.get('SPOTIPY_CLIENT_ID', 'YOUR_CLIENT_ID')
client_secret = os.environ.get('SPOTIPY_CLIENT_SECRET', 'YOUR_CLIENT_SECRET')
if client_id == 'YOUR_CLIENT_ID' or client_secret == 'YOUR_CLIENT_SECRET':
print("Please set SPOTIPY_CLIENT_ID and SPOTIPY_CLIENT_SECRET environment variables.")
else:
auth_manager = SpotifyClientCredentials(client_id=client_id, client_secret=client_secret)
sp = Spotify(auth_manager=auth_manager)
# Example: Search for an artist
try:
results = sp.search(q='artist:Queen', type='artist')
if results['artists']['items']:
artist = results['artists']['items'][0]
print(f"Found artist: {artist['name']} (ID: {artist['id']})")
albums = sp.artist_albums(artist['id'], album_type='album')
print("Latest albums:")
for album in albums['items'][:3]:
print(f"- {album['name']}")
else:
print("Artist not found.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingSpotify API update in 2026-02-06 changed `/tracks` endpoints to `/items`. Spotipy 2.26.0 updates its internal methods to reflect this, but direct usage of older endpoint names or expecting previous data structures might break. The playlist item limit has also been fixed to 50 items per request, requiring pagination for larger playlists.fixEnsure your code uses generic 'get user saved items' methods where applicable and handles pagination for playlists correctly. Review official Spotify API documentation for endpoint changes if directly interacting with API responses.
affects: >=2.26.0
deprecatedSeveral methods and parameters have been deprecated in recent versions (e.g., `artist_albums(album_type=...)` replaced by `include_groups`, `recommendations`, `audio_features`, `featured_playlists`, `category_playlists`). Use of these will trigger warnings and they may be removed in future versions.fixConsult the Spotipy documentation and changelog for the recommended replacement functions and parameters (e.g., use `include_groups` instead of `album_type` for `artist_albums`).
affects: >=2.25.0
gotchaSpotify has restricted access to algorithmic and Spotify-owned editorial playlists for new applications (post-2024). Attempts to retrieve these playlists via the API may result in errors or empty responses, even with proper user authentication and scopes.fixFocus on user-created or third-party playlists. If your application was created before 2024, it might still have access, but new applications will not. Verify playlist accessibility directly on the Spotify Developer Dashboard.
affects: All versions for apps created post-2024
gotchaUsing the Authorization Code Flow requires adding a redirect URI to your application settings on the Spotify Developer Dashboard. This URI must exactly match the `redirect_uri` provided to `SpotifyOAuth`, including trailing slashes. A common mistake is using `http://localhost/` or `http://127.0.0.1:9090` without configuring it in Spotify's dashboard.fixRegister your chosen `redirect_uri` (e.g., `http://127.0.0.1:9090`) in your Spotify app settings and ensure it is consistently used in your code and environment variables (`SPOTIPY_REDIRECT_URI`).
affects: All versions using Authorization Code Flow
breakingMultiple security vulnerabilities (CVE-2025-66040, CVE-2025-27154, CVE-2023-23608) have been fixed in recent versions, addressing potential XSS in OAuth flow HTML, tightened cache file permissions (600), and path traversal.fixIt is highly recommended to upgrade to the latest Spotipy version (2.26.0 or newer) to ensure these security fixes are applied, especially if running with the default OAuth flow, in multi-user environments, or handling user inputs for Spotify IDs/URIs/URLs.
affects: <2.25.2
Errors
Common errors & fixes
spotipy.exceptions.SpotifyException: The access token expired
The Spotify access token used for authentication has expired or is no longer valid, requiring a refresh or re-authentication.
fixEnsure your `SpotifyOAuth` instance is configured with a `cache_path` to automatically store and refresh tokens, or manually refresh the token using `SpotifyOAuth`'s refresh methods.
spotipy.oauth2.SpotifyOauthError: redirect_uri_mismatch
The `redirect_uri` provided in your Spotipy code does not exactly match one of the redirect URIs registered for your application in the Spotify Developer Dashboard.
fixGo to your Spotify Developer Dashboard, select your application, navigate to 'Edit Settings', and add or verify that the `redirect_uri` used in your code (e.g., `http://localhost:8888/callback`) is listed there and matches precisely.
ModuleNotFoundError: No module named 'spotipy'
The `spotipy` library has not been installed in your current Python environment or is not accessible.
fixInstall the `spotipy` library using pip: `pip install spotipy`
AttributeError: 'Spotify' object has no attribute 'user_playlist_add_tracks'
The `Spotify` object was not initialized with an appropriate authentication manager (e.g., `SpotifyOAuth` for user-specific actions) or lacks the required scopes for the requested operation.
fixInitialize `spotipy.Spotify` with `SpotifyOAuth` and ensure all necessary scopes (e.g., `playlist-modify-public`) are requested for the actions you intend to perform.
TypeError: 'str' object is not iterable
A Spotipy method that expects a list of IDs (e.g., track IDs, artist IDs) was incorrectly passed a single ID as a string.
fixWrap the single item ID in a list, even if you are only passing one item, for methods that expect iterable arguments.
Upgrade
Version history
2.26.0latest on PyPI · released Mar 3, 2026
Audit
Dependencies
pymemcacheoptionalOptional cache handler for Memcached.
redisoptionalOptional cache handler for Redis.
FlaskoptionalOptional cache handler for Flask sessions.