lastfm-export

Export your Last.fm listening history (scrobbles) and optionally enrich it with Spotify metadata.

Designed for both:

• CLI-first users who want “just get my data”, and
• Python users who want reusable clients and pipelines.

---

Features

• Export scrobbles from Last.fm with paging + retry/backoff.
• Optional Spotify enrichment (track metadata lookup).
• Streaming-friendly outputs (NDJSON recommended).
• Works with environment variables (no secrets in code).

---

Install

Using uv:

uv pip install lastfm-export

Or with .env support for local development:

uv pip install "lastfm-export[dotenv]"

---

Authentication

Last.fm

Set these environment variables:

export LASTFM_API_KEY="..."
export LASTFM_USERNAME="..."

Last.fm privacy setting: Exporting scrobbles requires your recent listening information to be available through the Last.fm API. Make sure “Hide recent listening information” is disabled in your Last.fm privacy settings. This setting controls whether your recent listening information is publicly visible.

Spotify (optional)

Set these environment variables:

export SPOTIFY_CLIENT_ID="..."
export SPOTIFY_CLIENT_SECRET="..."

If you installed lastfm-export[dotenv], you can also put these values in a local .env file.

---

Quickstart (CLI)

1) Export scrobbles

Recommended output format: NDJSON (one JSON object per line).

lastfm-export scrobbles export \
  --out scrobbles.ndjson

Optional filters:

lastfm-export scrobbles export \
  --out scrobbles.ndjson \
  --from YYYY-MM-DD \
  --to YYYY-MM-DD

You can also pass full datetimes:

lastfm-export scrobbles export \
  --out scrobbles.ndjson \
  --from YYYY-MM-DDTHH:MM:SS \
  --to YYYY-MM-DDTHH:MM:SS

Resume (incremental export):

lastfm-export scrobbles export \
  --out scrobbles.ndjson \
  --resume auto

2) Enrich with Spotify

lastfm-export enrich spotify \
  --in scrobbles.ndjson \
  --out scrobbles_enriched.ndjson

Notes:

• Spotify enrichment is best-effort: some tracks may not match cleanly.
• Use NDJSON for large exports.

---

Quickstart (Python)

Export scrobbles

from lastfm_export.clients.lastfm import LastFMClient
from lastfm_export.pipelines.lastfm_export import export_scrobbles

lastfm = LastFMClient(
    api_key="...",
    username="...",
    user_agent="lastfm-export",
)

for scrobble in export_scrobbles(lastfm=lastfm):
    print(scrobble.to_record())

Enrich with Spotify

from lastfm_export.clients.spotify import SpotifyClient
from lastfm_export.pipelines.spotify_enrich import enrich_scrobbles_with_spotify

spotify = SpotifyClient(
    client_id="...",
    client_secret="...",
    user_agent="lastfm-export",
)

enriched = enrich_scrobbles_with_spotify(spotify=spotify, scrobbles=export_scrobbles(lastfm=lastfm))
for row in enriched:
    print(row.to_record())

---

Output formats

Supported formats depend on command:

• NDJSON: recommended for streaming and incremental runs.
• JSON array: convenient for small exports.
• CSV: convenient for spreadsheets.

Tip: For large histories, use NDJSON to avoid loading everything into memory.

Raw source payloads

Normalized output remains the default. To also preserve the per-track source payload, use --include-raw:

lastfm-export scrobbles export \
  --out scrobbles.ndjson \
  --include-raw

lastfm-export enrich spotify \
  --in scrobbles.ndjson \
  --out scrobbles_enriched.ndjson \
  --include-raw

For Python usage, pass include_raw=True to to_record(). Last.fm payloads are stored in raw, while Spotify payloads are stored in spotify.raw. In CSV output, nested payloads are JSON-encoded in cells.

Raw payload shapes are controlled by the upstream APIs and may change independently of the normalized export schema.

---

Development

Clone the repo and set up the environment with uv:

uv venv
uv sync

Run checks:

uv run ruff check .
uv run pytest -q

Build:

uv build --no-sources

---

License

See LICENSE.