Library / SDK
spotipy-dev/spotipy avatar
spotipy-dev/spotipy

Spotipy wraps the Spotify Web API in one client object, and its base install still pulls in redis

A light weight Python library for the Spotify Web API

5,486 stars967 forksPythonMIT

At a glance

What is it?
Spotipy hands credential work to an auth manager you pass into a single client object, which makes catalog calls short but leaves retries, rate limits and caching out of the README. The packaging tells its own story too, with redis sitting in install_requires under a TODO for version 3.
Who is it for?
Spotipy suits scripts that read the catalog or one person's saved tracks and stop there. Pass on it if you need documented retry behaviour, rate limit handling or cache tuning, since the README describes none of them.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 146 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • spotipy-dev/spotipy5,486 ★ · +15
Star history
Repository2026-09-232026-11-21
spotipy-dev/spotipy5.5k5.5k

15 Stars in the last 59 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

One auth_manager argument decides what the client can reach

Every documented example begins with the same constructor: `spotipy.Spotify(auth_manager=...)`. Credentials are not passed to each call, they are wrapped in an object and handed to the client once, and the two documented objects decide what the client can reach. `SpotifyClientCredentials` from `spotipy.oauth2` carries `client_id` and `client_secret` only. `SpotifyOAuth` carries those same two keys plus `redirect_uri` and `scope`. Once the client exists, method names follow the API surface: `sp.search(q='weezer', limit=20)` returns a dictionary with a `tracks` key, and `sp.current_user_saved_tracks()` returns a dictionary with an `items` key. No other constructor options appear in the quick start, so caching, retries and timeouts are not configured there.

Client credentials reach the catalog and stop short of a listener

A client built from `client_id` and `client_secret` has no listener attached to it. The example without user authentication makes that concrete: it builds the client with `SpotifyClientCredentials`, runs one search for the string `weezer` with `limit=20`, then prints `track['name']` for each entry under `results['tracks']['items']`. That covers catalog lookups and direct field access into the returned dictionaries, and nothing more. `sp.current_user_saved_tracks()` needs an account behind the token, so it belongs to the other example. The quick start does not show swapping managers on a live client either, since each snippet constructs `spotipy.Spotify` again with the manager the task needs.

The install is one command and a dashboard app

The install comes down to three documented lines:

bash
pip install spotipy
py -m pip install spotipy
pip install spotipy --upgrade

The second form is the Windows path and the third upgrades an existing install. Your first credential does not come from this package. You create an account or log in at https://developers.spotify.com/, open the dashboard, create an app, and take the ID and SECRET from that app's settings page. The README examples pass them as plain constructor arguments and tell you to add them to your environment. The same file sets `python_requires='>3.8'`, which is the interpreter floor for everything else in this article.

redis sits in install_requires under a TODO for version 3

setup.py lists three runtime dependencies for every caller, and the first one is a cache client most callers never touch:

python
    install_requires=[
        "redis>=3.5.3",  # TODO: Move to extras_require in v3
        "requests>=2.25.0",
        "urllib3>=1.26.0"
    ],

`redis>=3.5.3` resolves on every plain install whether or not a Redis server exists anywhere in your setup, and the inline comment shows the maintainers already count it as a mistake to clear in v3. The optional groups are handled with more care: `extras_require` holds a `memcache` group with `pymemcache>=3.5.2`, and a `test` group with `autopep8>=2.3.2`, `flake8>=7.3.0`, `flake8-use-fstring>=1.4` and `isort>=7.0.0`. Caching is a choice you make with an extra today. Redis is not.

The user flow turns on a redirect URI and one scope string

User scoped calls need one piece of setup outside the library: a redirect URI added to the application in the dashboard, otherwise `SpotifyOAuth` has nothing to return the browser to.

python
sp = spotipy.Spotify(auth_manager=SpotifyOAuth(client_id="YOUR_APP_CLIENT_ID",
                                               client_secret="YOUR_APP_CLIENT_SECRET",
                                               redirect_uri="YOUR_APP_REDIRECT_URI",
                                               scope="user-library-read"))

The value you pass is handed to Spotify and the browser comes back to it, so the string has to match what you registered. `scope` is a space separated list of permissions, and the one documented value here is `user-library-read`, which is exactly what `sp.current_user_saved_tracks()` needs in order to return your liked songs. The README names no other scope value, and the token exchange, refresh and expiry handling behind that argument are not described on this page either.

Two of the last three releases are titled with CVE numbers

The recent releases are named after their own reason for existing. 2.25.1, dated 2025-02-27, reads `2.25.1: CVE-2025-27154`. 2.25.2, dated 2025-11-26, reads `2.25.2: CVE-2025-66040`. 2.26.0, dated 2026-03-03, reads `2.26.0: Deprecated methods`. Two security releases about nine months apart, followed by a release named for deprecations rather than additions, is the shape of that history, and the changelog is where the specifics live. The default branch master took its last push on 2026-06-29 and the repository is not archived, so the code does move. What the README will not do is tell you which methods 2.26.0 deprecated, so read CHANGELOG.md before you pin that version in anything long lived.

Issue and source links still resolve to plamere

The repository lives at spotipy-dev/spotipy, yet two pointers inside it still carry the older path. The bug report link in the README goes to https://github.com/plamere/spotipy/issues, and setup.py records `author="@plamere"`, `author_email="[email protected]"` and a `Source` project URL of https://github.com/plamere/spotipy. The examples link moves the other way, pointing at the spotipy-examples repository under spotipy-dev, so the rename reached some links and not others. Filing an issue straight from the README leaves the current repository behind. Documentation is the one pointer that agrees with setup.py's `url` field, since both use https://spotipy.readthedocs.org/. With `packages=['spotipy']`, the installable surface is a single import package and everything else stays in the tree.

Retries, rate limits and cache behaviour go undocumented

The omissions matter more than the feature claims for anyone planning a long running job. There is nothing about retrying a failed request, nothing about rate limits or quota, and no statement of what the `memcache` extra caches or when it is consulted. Pagination shows up only as an iteration over `results['items']`, with no page size or offset argument spelled out. Token refresh for `SpotifyOAuth` is not mentioned. In practice every call returns what the platform returns, and the README is silent on the surrounding failure modes. Production use means reading FAQ.md, TUTORIAL.md and the online documentation, not the install snippet.

Editorial conclusion

Spotipy suits scripts that read the catalog or one person's saved tracks and stop there. Pass on it if you need documented retry behaviour, rate limit handling or cache tuning, since the README describes none of them. Before pinning version 2.26.0, read CHANGELOG.md for the methods that release deprecated, and register the redirect URI in the dashboard before the first request that needs a user.

Frequently asked questions

Is Spotipy a Python library?

Yes. Spotipy is a lightweight Python library for the Spotify Web API, released under the MIT license. setup.py declares version 2.26.0 and asks for a Python newer than 3.8.

How do I install Spotipy?

Run pip install spotipy. The README also gives py -m pip install spotipy for Windows users and pip install spotipy --upgrade for an existing install. Beyond that you need an app on the Spotify dashboard for a client ID and secret.

How do I search for a song using Spotipy?

Build a client with SpotifyClientCredentials holding your app's client_id and client_secret, then call sp.search(q='weezer', limit=20) and read the entries under results['tracks']['items'].

How do I use Spotipy with user authentication?

Add a redirect URI to your app in the Spotify dashboard first, then build the client with SpotifyOAuth and pass client_id, client_secret, redirect_uri and a scope such as user-library-read, which is what sp.current_user_saved_tracks() needs.

What is Spotipy used for?

It wraps the Spotify Web API so Python code can query the catalog and read a listener's saved tracks. The quick start demonstrates sp.search and sp.current_user_saved_tracks, and points further examples at the online documentation and the spotipy-examples repository.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. spotipy-dev/spotipy on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/spotipy-dev-spotipy.svg)](https://hysenlabs.com/projects/spotipy-dev-spotipy)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/spotipy-dev-spotipy.svg)](https://hysenlabs.com/projects/spotipy-dev-spotipy)

Was this useful?