SpotifyScraper¶

Try it live

Paste any Spotify link into the browser demo and watch SpotifyScraper return typed data, cover art, and a preview — with the exact Python that produced it.

Extract public Spotify data — tracks, albums, artists, playlists, and podcasts — with one dependency and no API key.

SpotifyScraper reads the same public pages your browser does and returns clean, typed Python objects. There is no app to register, no client secret to manage, and no OAuth dance: just install it and call a method.

One runtime dependency

The core depends only on httpx. Media tagging and the browser fallback are opt-in extras.
No API key, no credentials

Public metadata comes from anonymous endpoints. Nothing to register.
Typed & immutable

Every entity is a frozen dataclass with a JSON-safe to_dict().
Sync and async

SpotifyClient and AsyncSpotifyClient share one core.

30-second example¶

from spotify_scraper import SpotifyClient

with SpotifyClient() as client:
    track = client.get_track("4uLU6hMCjMI75M1A2tKUQC")
    print(f"{track.name} — {track.artists[0].name}")
    print(f"{track.duration_ms / 1000:.0f} seconds")

    # A JSON-safe dict you can serialize anywhere:
    data = track.to_dict()
    print(data["uri"])

Never Gonna Give You Up — Rick Astley
213 seconds
spotify:track:4uLU6hMCjMI75M1A2tKUQC

You pass a Spotify URL, URI, or bare 22-character ID — all three work interchangeably:

client.get_track("https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC")
client.get_track("spotify:track:4uLU6hMCjMI75M1A2tKUQC")
client.get_track("4uLU6hMCjMI75M1A2tKUQC")

Install¶

pip install spotifyscraper

Install target	What you get
`spotifyscraper`	Core library: all entities, cover/preview downloads (no tagging).
`spotifyscraper[media]`	Adds `mutagen` so previews can embed cover art and ID3 tags.
`spotifyscraper[browser]`	Adds a Playwright Chromium transport for sites that challenge plain HTTP clients.
`spotifyscraper[all]`	Everything above.

See Installation for uv, extras, and the Playwright browser download step.

Supported Python versions¶

SpotifyScraper supports Python 3.10, 3.11, 3.12, and 3.13.

What you can fetch¶

Method	Returns
`get_track(value)`	A `Track`
`get_album(value)`	An `Album` with its track list
`get_artist(value)`	An `Artist`
`get_playlist(value, max_tracks=100)`	A `Playlist`
`get_episode(value)`	An `Episode`
`get_show(value, max_episodes=50)`	A `Show` with its episodes

Head to the Quickstart to see each one, or the Entities guide for the full field reference.

Async in one glance¶

import asyncio
from spotify_scraper import AsyncSpotifyClient

async def main() -> None:
    async with AsyncSpotifyClient() as client:
        track = await client.get_track("4uLU6hMCjMI75M1A2tKUQC")
        print(track.name)

asyncio.run(main())

The async client mirrors the sync one method-for-method. See the Async guide for asyncio.gather bulk patterns.

Command-line interface¶

A spotifyscraper command is available now — install the cli extra and print any entity as JSON or download cover art and previews:

pip install "spotifyscraper[cli]"
spotifyscraper track 4uLU6hMCjMI75M1A2tKUQC | jq -r '.name'

See the CLI guide for every command, options, and exit codes.

Roadmap¶

SpotifyScraper ships the core library — all six entity types, media downloads, anti-ban resilience, the browser fallback — plus the command-line interface.

Version	Adds
3.0.0	Core library.
3.1.0	The command-line interface.
3.2.0	Cookie-authenticated lyrics extraction (this release).

Planned¶

Upcoming work is tracked in the GitHub milestones:

Version	Adds
3.3	Podcast transcripts and first-class authenticated sessions — browser-assisted login with a persistent cookie store (no stored passwords).
3.4	Search across every entity type and market / region support.
3.5	Optional response caching and batch helpers with managed concurrency.

Scope is subject to change — 👍 the issues that matter most to you.

Lyrics are available

Cookie-authenticated lyrics extraction has shipped: client.get_lyrics(track) and the spotifyscraper lyrics command. See the Lyrics & cookies guide.

Legal & terms of service

SpotifyScraper is intended for personal, educational, and research use. You are responsible for complying with Spotify's Terms of Service and applicable copyright law. The preview clips and cover art returned by this library are owned by their respective rights holders. Read the Legal & ToS page before deploying.