spotify-utils

2.0.1 verified Sat May 09 auth: no python

A CLI and TUI tool for various Spotify utility tasks like playlist management, export, and import. Current version 2.0.1, released Sep 2025. Active development with frequent minor releases.

pip install spotify-utils

Common errors

error ModuleNotFoundError: No module named 'spotify_utils' ↓

cause The package is named `spotify-utils` with a hyphen, but import uses underscore.

fix

Install with pip install spotify-utils and import as import spotify_utils.

error ImportError: cannot import name 'SpotifyClient' from 'spotify_utils.client' ↓

cause SpotifyClient was moved to the top-level package in v2.0.0.

fix

Use from spotify_utils import SpotifyClient.

error spotify_utils.exceptions.AuthenticationError: Invalid client credentials ↓

cause Missing or incorrect SPOTIFY_CLIENT_ID / SPOTIFY_CLIENT_SECRET environment variables or parameters.

fix

Set the environment variables or pass them directly to the constructor. Verify credentials on Spotify Developer Dashboard.

Warnings

breaking v2.0.0 renamed the main package from 'spotify_utils' to 'spotify_utils' (no change) but moved `SpotifyClient` to top-level import. Old import path `from spotify_utils.client import SpotifyClient` no longer works. ↓

fix Use `from spotify_utils import SpotifyClient` for v2.x.

deprecated The `export` command format templates changed in v1.1.0. Old custom templates (Jinja2 based) may break if using deprecated placeholders. ↓

fix Review new template format in docs; old placeholders like `{{ track }}` should be `{{ track.name }}`.

gotcha Spotify OAuth requires a redirect URI exactly matching the one registered in Spotify App Dashboard. Use `http://localhost:8888/callback` for local development. ↓

fix Ensure `redirect_uri` in code matches the callback URL in your Spotify App settings.

gotcha Rate limits: Spotify API has a limit of 100 requests per 30 seconds. Bulk operations may fail silently if not handling HTTP 429. ↓

fix Implement exponential backoff or use the built-in retry mechanism (available since v1.0.14).

Imports

SpotifyClient

wrong

from spotify_utils.client import SpotifyClient

correct

from spotify_utils import SpotifyClient

SpotifyClient is exposed at the package level since v2.0.0

PlaylistManager

from spotify_utils.playlist import PlaylistManager

Quickstart

Initialize client with Spotify OAuth credentials and fetch playlists.

from spotify_utils import SpotifyClient
import os

client = SpotifyClient(
    client_id=os.environ.get('SPOTIFY_CLIENT_ID', ''),
    client_secret=os.environ.get('SPOTIFY_CLIENT_SECRET', ''),
    redirect_uri=os.environ.get('SPOTIFY_REDIRECT_URI', 'http://localhost:8888/callback')
)
# List first 10 playlists
playlists = client.get_playlists(limit=10)
for pl in playlists:
    print(pl['name'])