Spotipy

Warnings

• breaking Spotify 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.
  Fix: Ensure 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.
• deprecated Several 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.
  Fix: Consult the Spotipy documentation and changelog for the recommended replacement functions and parameters (e.g., use `include_groups` instead of `album_type` for `artist_albums`).
• gotcha Spotify 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.
  Fix: Focus 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.
• gotcha Using 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.
  Fix: Register 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`).
• breaking Multiple 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.
  Fix: It 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.

Install

• pip install spotipy Install stable version
• pip install spotipy --upgrade Upgrade to latest

Imports

• 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

  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.

Quickstart

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}")