SpotifyScraper

Extract public Spotify data — tracks, albums, artists, playlists, and podcasts — without the official API or any credentials.

SpotifyScraper bootstraps an anonymous token from Spotify's own public embed pages and reads the same JSON endpoints the web player uses, returning typed, immutable models. v3 is a ground-up rewrite focused on reliability and a clean, modern API.

Upgrading from v2? See the migration guide. The previous line lives on the v2.x branch.

Install

pip install spotifyscraper                 # core (only depends on httpx)
pip install "spotifyscraper[media]"        # + cover/preview embedding (mutagen)
pip install "spotifyscraper[browser]"      # + Playwright browser fallback
pip install "spotifyscraper[cli]"          # + the spotifyscraper command-line tool
pip install "spotifyscraper[all]"          # everything

Python 3.10+.

Quickstart

from spotify_scraper import SpotifyClient

with SpotifyClient() as client:
    track = client.get_track("https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC")
    print(track.name, "—", track.artists[0].name)
    print(track.duration_ms, "ms |", track.preview_url)

    print(track.to_dict())          # JSON-safe dict, if you prefer dicts

Every entity has its own method — get_track, get_album, get_artist, get_playlist, get_episode, get_show — each accepting a URL, URI, or bare ID.

Async

import asyncio
from spotify_scraper import AsyncSpotifyClient

async def main():
    async with AsyncSpotifyClient() as client:
        track, album = await asyncio.gather(
            client.get_track("4uLU6hMCjMI75M1A2tKUQC"),
            client.get_album("4aawyAB9vmqN3uQ7FjRGTy"),
        )
        print(track.name, "|", album.name)

asyncio.run(main())

Download a cover and preview

from spotify_scraper import SpotifyClient

with SpotifyClient() as client:
    track = client.get_track("4uLU6hMCjMI75M1A2tKUQC")
    client.download_cover(track, dest="covers/")
    client.download_preview(track, dest="previews/", embed_cover=True)  # needs [media]

Features

All core entities + podcasts — tracks, albums, artists, playlists, shows, episodes.
Sync & async clients sharing one sans-io core.
Typed, frozen models with JSON-safe to_dict() / from_dict().
Two-tier resilience — Spotify's GraphQL API with automatic fallback to the embed page.
One core dependency (httpx); media and browser support are optional extras.
Anti-ban built in — per-host rate limiting, retries with backoff, UA rotation, proxies.
Browser fallback via Playwright when you need a real browser.

Command line

With the cli extra installed, a spotifyscraper command is available:

spotifyscraper track 4uLU6hMCjMI75M1A2tKUQC          # entity metadata as JSON
spotifyscraper playlist <id> --max-tracks 50 --pretty
spotifyscraper download preview <id> -o ./previews --embed-cover

Every command emits JSON, so it composes with tools like jq. See the CLI guide.

Lyrics

Lyrics need a Spotify account cookie (sp_dc); the library handles the token handshake for you:

from spotify_scraper import SpotifyClient

with SpotifyClient(cookies="cookies.txt") as client:   # or cookies={"sp_dc": "..."}
    lyrics = client.get_lyrics("4uLU6hMCjMI75M1A2tKUQC")
    for line in lyrics.lines:
        print(line.start_ms, line.text)

Your cookie is sent only to Spotify and never logged. See the lyrics guide.

Roadmap

Version	Scope
3.0	The library: all entities, pagination, media downloads, browser fallback, docs
3.1	Command-line interface
3.2	Cookie-authenticated lyrics

Documentation

Full docs, guides, and the API reference: https://spotifyscraper.readthedocs.io

Legal

SpotifyScraper is an unofficial, independent project, not affiliated with Spotify. It reads publicly available data and the ~30-second previews Spotify publishes; it does not download full tracks or circumvent DRM. Use it for educational and personal purposes, and in line with Spotify's Terms of Service. See the legal notice.

Contributing

Contributions are welcome — see CONTRIBUTING.md. The project is developed spec-first with OpenSpec; specs live in openspec/.

License

MIT © Ali Akhtari

Metadata

Release files for spotifyscraper 3.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for spotifyscraper 3.2.0
File	Size	Uploaded
spotifyscraper-3.2.0.tar.gz	297.1 kB	Jun 13, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for spotifyscraper 3.2.0
File	Interpreter	ABI	Platform	Reset
spotifyscraper-3.2.0-py3-none-any.whl 66.7 kB Jun 13, 2026	Python 3	none	any	Details

Total release size: 363.7 kB

Release files / spotifyscraper-3.2.0.tar.gz

Download URL	spotifyscraper-3.2.0.tar.gz
Size	297.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`23f45bfeb9354f2fb14784f8670f1e8c404a0678b0c7d79d507c66f4a04a7e17`
BLAKE2b-256 checksum How to use checksums	`f0eb4bdc73fe3beca481dafe89a3b04feb8bb1196180bcaca7b67906ae8a9996`
Upload date	Jun 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Release files / spotifyscraper-3.2.0-py3-none-any.whl

Download URL	spotifyscraper-3.2.0-py3-none-any.whl
Size	66.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`af4be91e7040949e8e11cd69a41d2d76b8ad9970be9bb8c0ccfc604c3b0ae8be`
BLAKE2b-256 checksum How to use checksums	`303a28529ccce4bc73f320d3d4fc16bc57f1ad11dbb6936afc62a1a1e7ec786a`
Upload date	Jun 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`