spotifyaio

library2.0.2pypypi✓ verified 84d ago

Asynchronous Python client for the Spotify Web API, built on aiohttp. Current version 2.0.2, requires Python >=3.13. Actively maintained with frequent releases.

http-networking

pip install spotifyaio

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · SPOTIFYAIO

spotifyaio

http-networkingpythonv2.0.2

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 spotifyaio import SpotifyClient

Quickstart: authenticate and fetch a track by ID.

import asyncio from spotifyaio import SpotifyClient async def main(): client_id = os.environ.get('SPOTIFY_CLIENT_ID', '') client_secret = os.environ.get('SPOTIFY_CLIENT_SECRET', '') async with SpotifyClient(client_id=client_id, client_secret=client_secret) as client: track = await client.tracks.get('4cOdK2wGLETKBW3PvgPWqT') print(track.name) asyncio.run(main())

Debug

Known issues

breakingVersion 2.0.0 drops Python 3.12 support; only Python >=3.13 is supported.

fix

Upgrade Python to 3.13 or later, or pin spotifyaio to <2.0.0 if Python 3.12 is required.

affects: <2.0.0

breakingVersion 1.0.0 drops Python 3.11 support; only Python >=3.12 was supported at that time, but v2.0.0 now requires 3.13.

fix

Upgrade Python accordingly.

affects: <1.0.0

gotchaThe client must be used as an async context manager. Forgetting 'async with' will lead to unclosed session warnings.

fix

Always use `async with SpotifyClient(...) as client:` or explicitly call `await client.close()`.

affects: all

gotchaAPI calls may return None for optional fields. Always check for None before accessing nested attributes.

fix

Use `track.name` safely by checking `if track:` or use `.get()` if available.

affects: all

Errors

Common errors & fixes

TypeError: ClientSession.__aenter__() got multiple values for argument 'self'

Incorrect instantiation of SpotifyClient without async context manager, or reusing a session improperly.

fix

Use `async with SpotifyClient(...) as client:` pattern.

spotifyaio.exceptions.SpotifyError: 401 - Unauthorized

Invalid or expired client credentials (client_id/client_secret).

fix

Verify credentials from Spotify Developer Dashboard and set environment variables correctly.

spotifyaio.exceptions.SpotifyError: 429 - Too Many Requests

Rate limit exceeded. The client does not automatically throttle requests.

fix

Implement your own rate limiting or add delays between requests.

Upgrade

Version history

2.0.2latest on PyPI · released Mar 4, 2026

Audit

Dependencies

aiohttprequiredHTTP client used for all API requests

yarlrequiredURL handling

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/joostlek/python-spotify ↗

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

docshttps://github.com/joostlek/python-spotify ↗

changeloghttps://github.com/joostlek/python-spotify/releases ↗