SpotifySaver

0.7.5 verified Sat May 09 auth: no python

Download Spotify tracks/albums/playlists with metadata via YouTube Music, designed for Jellyfin libraries. Current version 0.7.5, requires Python 3.9-3.12. Development is active with regular releases.

pip install spotifysaver

Common errors

error ModuleNotFoundError: No module named 'spotifysaver' ↓

cause Package not installed or imported with wrong name (e.g., spotify_saver).

fix

Run pip install spotifysaver and import as from spotifysaver import SpotifySaver.

error spotifysaver: error: argument command: invalid choice: 'download' (choose from 'run', 'init', 'serve', 'version') ↓

cause Using deprecated `download` subcommand instead of `run`.

fix

Use spotifysaver run <url> instead of spotifysaver download <url>.

error ValueError: Missing Spotify API credentials. Set SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET. ↓

cause Environment variables not set.

fix

Run spotifysaver init to create .env file with your credentials, or export them manually.

error Error: 'NoneType' object has no attribute 'get' ↓

cause Occurs when a track/album URL is invalid or not found on Spotify.

fix

Double-check the URL and ensure it points to a valid Spotify track, album, or playlist.

Warnings

gotcha The SpotifySaver class requires valid Spotify API credentials. Set SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET in environment variables or .env file before calling download(). ↓

fix Set environment variables or run `spotifysaver init` to create .env file interactively.

breaking In v0.6.0, the default download format changed from m4a to opus. If you rely on m4a output, you must explicitly set format='m4a' when initializing SpotifySaver or in config. ↓

fix Specify format='m4a' in constructor or set in .env: SPOTIFYSAVER_FORMAT=m4a.

deprecated The CLI command `spotifysaver download` is deprecated in favor of `spotifysaver run` (v0.5.0+). ↓

fix Use `spotifysaver run <url>` instead.

gotcha Playlist downloads create a single directory without subdirectories per artist/album. If you need subdirectories, consider using the API and handling paths manually. ↓

fix No built-in workaround; feature request pending.

gotcha If you run the API server (`spotifysaver serve`), the web UI is served on port 8000 by default. Ensure that port is not in use. ↓

fix Change port with `spotifysaver serve --port 8080` or set SERVER_PORT in .env.

Imports

SpotifySaver
wrong
```
from spotify_saver import SpotifySaver
```
correct
```
from spotifysaver import SpotifySaver
```
Hyphen in GitHub repo name, but PyPI package uses no hyphen.

run_cli

wrong

from spotifysaver import run_cli

correct

from spotifysaver.cli import run_cli

CLI entry point is in the cli submodule.

Quickstart

Download a Spotify track by URL.

from spotifysaver import SpotifySaver
import os

# Initialize with Spotify API credentials (set in .env or environment)
os.environ['SPOTIFY_CLIENT_ID'] = os.environ.get('SPOTIFY_CLIENT_ID', 'your_client_id')
os.environ['SPOTIFY_CLIENT_SECRET'] = os.environ.get('SPOTIFY_CLIENT_SECRET', 'your_client_secret')

saver = SpotifySaver()
saver.download('https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT')