spotifyify

An async-first Spotify client built on HTTPX2, with a namespaced API and fully typed response models maintained in the codebase and aligned with the official Spotify OpenAPI specification.

See the 0.9 migration guide for renamed APIs, explicit login, API modes and output changes. Spotifyify remains a compatibility alias. The 0.9.0 release notes summarize the changes, including the removal of the optional CLI and the switch to HTTPX2.

Requirements

• Python 3.13+
• A Spotify app registered at developer.spotify.com
• Development Mode requires an active Premium subscription for the app owner; see Spotify's API-mode requirements.

Installation

pip install spotifyify

With uv:

uv add spotifyify

Configuration

Credentials are loaded from environment variables (or a .env file via pydantic-settings):

.env example:

SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback
SPOTIFY_REFRESH_TOKEN=your_refresh_token

If SPOTIFY_REFRESH_TOKEN (or SPOTIFY_ACCESS_TOKEN) is present the client operates in user mode. Without them it falls back to the Client Credentials flow, which only allows access to public data.

User authorization

User-scoped calls require an existing user grant. API calls never open a browser or prompt for input. Supply a user access/refresh token through the environment, or authorize explicitly with the Python OAuth helpers:

import asyncio
import secrets
import webbrowser

from spotifyify import SpotifyCredentials
from spotifyify.cache_handler import CacheFileHandler
from spotifyify.oauth2 import SpotifyOAuth
from spotifyify.oauth2.callback import capture_local_code

async def login():
    credentials = SpotifyCredentials()
    if not credentials.redirect_uri:
        raise ValueError("Set SPOTIFY_REDIRECT_URI before authorizing")
    cache = CacheFileHandler(client_id=credentials.client_id, profile="default")
    oauth = SpotifyOAuth(credentials, cache)
    try:
        state = secrets.token_urlsafe(32)
        scopes = ["user-read-playback-state", "user-modify-playback-state"]
        url = oauth.authorization_url(state=state, scope=scopes)
        code = await capture_local_code(
            credentials.redirect_uri,
            state=state,
            on_ready=lambda: webbrowser.open(url),
        )
        await oauth.exchange_code(code, scope=scopes)
    finally:
        await oauth.close()

asyncio.run(login())

Configure an explicit loopback redirect such as http://127.0.0.1:8888/callback for this example. The listener starts before the browser opens. Applications with their own callback handler can validate the redirect with parse_callback_url() and pass the code to exchange_code().

Use the same profile in CacheFileHandler(profile="work", ...) and SpotifyClient(cache_profile="work") to keep accounts separate. Tokens are cached per client ID and profile under the user's application data directory on Windows or $XDG_CACHE_HOME/spotifyify on Unix. Cache files are written atomically, with owner-only permissions on Unix and inherited user-profile ACLs on Windows. They contain unencrypted credentials. Existing project-local caches can be selected explicitly with CacheFileHandler(".cache"); the client does not import them automatically.

Bring your own user token

Multi-user backends can pass an already minted end-user access token for one request scope. While the context is active, spotifyify sends that token directly and skips its configured OAuth provider, app credentials, cache, refresh, and scope checks. Expired or insufficient tokens surface as Spotify API errors.

The token context is isolated per client instance and async task, so one shared SpotifyClient instance can serve concurrent users:

async with SpotifyClient() as spotify:
    async with spotify.request_context(access_token=end_user_access_token):
        playlist = await spotify.playlists.create("Weekly Mix", public=False)
        await spotify.playlists.replace(
            playlist.id,
            ["spotify:track:...", "spotify:track:..."],
        )

Quick start

import asyncio
from spotifyify import SpotifyClient, SpotifyScope

async def main():
    async with SpotifyClient(scopes=[SpotifyScope.USER_READ_PLAYBACK_STATE]) as sp:
        state = await sp.player.state()
        if state and state.item:
            print(f"Now playing: {state.item.name}")

asyncio.run(main())

API design

The default API contract is Spotify Development Mode (including the 2026 changes). Library writes/checks use /me/library, playlists are created with /me/playlists, and get_many() uses bounded individual reads. Search accepts at most 10 items per request in this mode. Endpoints Spotify removed from this mode fail locally with SpotifyUnsupportedOperation.

Apps that already have Extended Quota access can select the legacy-compatible contract with SpotifyClient(api_mode="extended"). This option selects endpoints; it does not change the app's Spotify quota mode.

get_many() accepts any number of IDs, batches where supported, and returns one entry per input ID in the same order. Missing entries are None. Configure parallel read workers with concurrency (default: 8). Empty input returns an empty list; pass [track_id] for one ID rather than a plain string.

Use iter_search(), library.iter_saved_tracks() (and the corresponding album, show and episode iterators), playlists.iter_items(), users.iter_following() or player.iter_recently_played() to consume pages lazily:

async for saved in spotify.library.iter_saved_tracks(limit=50):
    print(saved.track.name)

Playlist add(), remove() and replace() split large writes into ordered requests. These operations are not atomic across requests. If a later request fails, SpotifyBatchError exposes completed_items, total_items and the last snapshot_id; its cause retains the underlying error. Counts refer to processed input URIs, not the number of playlist entries removed. Restarting the whole operation can duplicate already applied changes, so recover using that progress.

The SpotifyClient class is the entry point. It exposes all Spotify resources as lazy-loaded namespace properties. Request methods are awaited; iter_* methods are consumed with async for.

SpotifyClient
├── .tracks      # Tracks, search
├── .artists     # Artists, top tracks, discography, related artists
├── .albums      # Albums, new releases
├── .playlists   # Playlists, CRUD, track management
├── .player      # Playback control, queue, devices, history
├── .library     # Saved tracks/albums/shows/episodes, top items
├── .shows       # Podcast shows
├── .episodes    # Podcast episodes
└── .users       # Current user, public profiles, following

Tracks — sp.tracks

Artists — sp.artists

Albums — sp.albums

Playlists — sp.playlists

Player — sp.player

Library — sp.library

time_range accepts "short_term", "medium_term", or "long_term".

Shows — sp.shows

Episodes — sp.episodes

Users — sp.users

Retries

Spotify API requests automatically retry rate limits (429) and temporary server errors (500, 502, 503, 504). Rate limits honor Spotify's Retry-After header. Server errors are retried only when the operation is safe to repeat. Configure the defaults with max_retries and retry_backoff_seconds when constructing SpotifyClient.

The default client adds jitter to exponential backoff, caps that backoff at 30 seconds and stops automatic retries when a planned wait exceeds 60 seconds. Rate limits cool concurrent requests on the same client. QUOTA_EXCEEDED responses and ambiguous playlist reorders are not retried. Supply a RetryPolicy to customize the retry count, backoff, jitter and maximum wait.

Use a request-context retry hook when planned retries should be reported to a caller before spotifyify sleeps and sends the request again. The hook is isolated per async task, so one shared SpotifyClient instance can be used by concurrent conversations. retry_number is one-based and retry_at contains the planned retry time in UTC:

from spotifyify import RetryEvent

async def on_retry(event: RetryEvent) -> None:
    await sse_bus.emit(
        conversation_id,
        {
            "status_code": event.status_code,
            "retry_number": event.retry_number,
            "max_retries": event.max_retries,
            "retry_after": event.retry_after,
            "retry_at": event.retry_at.isoformat(),
        },
    )

async with spotify.request_context(on_retry=on_retry):
    track = await spotify.tracks.get(track_id)

If all retries are exhausted and Spotify still returns 429, spotifyify raises SpotifyRateLimitError. It subclasses SpotifyAPIError and exposes retry_after and retry_at from Spotify's final Retry-After response header:

from spotifyify import SpotifyRateLimitError

try:
    track = await spotify.tracks.get(track_id)
except SpotifyRateLimitError as exc:
    await sse_bus.emit(
        conversation_id,
        {
            "status_code": exc.status_code,
            "retry_after": exc.retry_after,
            "retry_at": exc.retry_at.isoformat() if exc.retry_at else None,
            "message": exc.message,
        },
    )

Request-scoped options can be combined without nested context managers:

async with spotify.request_context(access_token=end_user_access_token, on_retry=on_retry):
    me = await spotify.users.me()

Scopes

Use SpotifyScope to declare the OAuth scopes your app requires:

from spotifyify import SpotifyScope

SpotifyScope.USER_READ_PLAYBACK_STATE
SpotifyScope.USER_MODIFY_PLAYBACK_STATE
SpotifyScope.USER_LIBRARY_READ
SpotifyScope.USER_LIBRARY_MODIFY
SpotifyScope.USER_TOP_READ
SpotifyScope.USER_READ_RECENTLY_PLAYED
SpotifyScope.PLAYLIST_MODIFY_PUBLIC
SpotifyScope.PLAYLIST_MODIFY_PRIVATE
SpotifyScope.PLAYLIST_READ_PRIVATE

Scopes can also be passed as plain strings.

Examples

See the examples/ directory for runnable Python scripts:

• examples/player/search_and_play.py — search for tracks and control playback with the Python API
• examples/playlists/manage_playlist.py — create and manage a playlist with the Python API
• examples/playlists/user_token_playlist.py — create playlists with caller-supplied user tokens
• examples/library/library_stats.py — explore your top tracks and saved library

Development

uv sync --frozen --group schema --group examples
uv run --no-sync pytest -q
uv run --no-sync ruff check spotifyify tests examples tools
uv run --no-sync ruff format --check spotifyify tests examples tools
uv run --no-sync pyright
uv build

The CI tests Windows and Linux with Python 3.13 and 3.14, including the Python client and MCP example. Model maintenance documents the pinned schema and comparison generator. The migration guide describes compatibility changes in 0.9.

Maintainers can follow the release checklist to validate and publish a version. CI builds distributions but does not publish them.