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

Verified mode is the default. It gets one UTC day at a time and checks for problems in Last.fm's response. Use it for exports you want to keep. If a check finds a problem, it stops by default. --integrity-policy warn continues and marks the export with warnings. A detailed integrity report is saved by default for failures and warning exports. Use --integrity-report always to also save one for clean exports, or --integrity-report never to suppress reports for successful exports.

For quick exploration or a small sample, you can explicitly choose the faster, unverified sequential paginator:

lastfm-export scrobbles export \
  --out sample.ndjson \
  --acquisition-mode fast \
  --page-limit 10

Fast mode uses Last.fm's normal page-by-page export. It is useful for quick checks or samples, but Last.fm can repeat or miss tracks. The export warns you but does not create a report by default. Use --integrity-report always to save an "unverified" report. Do not use it for backups or a full history export. It does not accept --integrity-policy.

Long-running commands show compact progress in a normal terminal. Use --progress off to hide it, or --progress on to keep it when running in a script or redirected terminal. Verified exports show a live status and one saved progress line for each completed quarter.

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.