SpotipyIO

1.1.1 verified Sat May 09 auth: no python

An async Python client for the Spotify Web API, supporting authentication, caching, and all major endpoints. Current version 1.1.1, requires Python 3.8–3.12. Released sporadically.

pip install spotipyio

Common errors

error ImportError: cannot import name 'SpotifyClient' from 'spotipyio' ↓

cause Installed an older version (<1.0.0) that used a different export pattern.

fix

Upgrade to spotipyio>=1.0.0 with pip install --upgrade spotipyio.

error spotipyio.exceptions.AuthenticationError: Invalid client credentials ↓

cause Missing or incorrect environment variables SPOTIPY_CLIENT_ID or SPOTIPY_CLIENT_SECRET.

fix

Set SPOTIPY_CLIENT_ID and SPOTIPY_CLIENT_SECRET environment variables with valid Spotify app credentials.

Warnings

breaking In version 1.0.0, the async API was rewritten. Sync methods were removed. All calls now require `await`. ↓

fix Upgrade to 1.1.1 and wrap all client calls with `await`.

gotcha Authentication flow requires a running HTTP server on localhost to capture the redirect. Without a properly configured redirect URI, authorization fails silently. ↓

fix Ensure your redirect_uri matches exactly what is set in the Spotify Developer Dashboard (e.g., http://localhost:8080/callback).

deprecated The `SpotifyClient` initializer parameter `cache_path` is deprecated and will be removed in v2.0. Use `token_cache` option instead. ↓

fix Replace `cache_path='/path/to/cache'` with `token_cache=FileCache('/path/to/cache')`.

Imports

SpotifyClient
wrong
```
from spotipyio.client import SpotifyClient
```
correct
```
from spotipyio import SpotifyClient
```
SpotifyClient is exported at package level, not from submodule.

Quickstart

Initialize a SpotifyClient with credentials and perform a search.

import asyncio
from spotipyio import SpotifyClient

async def main():
    client = SpotifyClient(
        client_id=os.environ.get('SPOTIPY_CLIENT_ID', ''),
        client_secret=os.environ.get('SPOTIPY_CLIENT_SECRET', ''),
        redirect_uri=os.environ.get('SPOTIPY_REDIRECT_URI', 'http://localhost:8080/callback')
    )
    # Example: search for an artist
    results = await client.search(q='Radiohead', type='artist', limit=1)
    print(results)

asyncio.run(main())