spotipyio

library1.1.1pypypi✓ verified 83d ago

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.

http-networking communication

pip install spotipyio

package ↗

INSTALL

IMPORT

SIG · SPOTIPYIO

spotipyio

http-networkingpythonv1.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SpotifyClient

✓ from spotipyio import SpotifyClient

✗ from spotipyio.client import SpotifyClient

SpotifyClient is exported at package level, not from submodule.

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())

Debug

Known issues

breakingIn 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`.

affects: <1.0.0

gotchaAuthentication 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).

affects: >=1.0.0

deprecatedThe `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')`.

affects: >=1.1.0

Errors

Common errors & fixes

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

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`.

spotipyio.exceptions.AuthenticationError: Invalid client credentials

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.

Upgrade

Version history

1.1.1latest on PyPI · released Sep 19, 2025

Audit

Dependencies

httpxrequiredHTTP client for async requests

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/spotipyio/ ↗