Skip to main content

pyLast

PyPI version Supported Python versions PyPI downloads GitHub Actions status Codecov Licence DOI Code style: Black

A Python interface to Last.fm and other API-compatible websites such as Libre.fm.

Use the pydoc utility for help on usage or see tests/ for examples.

Installation

Install via pip:

python3 -m pip install pylast

Install latest development version:

python3 -m pip install -U git+https://github.com/pylast/pylast

Or from requirements.txt:

-e https://github.com/pylast/pylast.git#egg=pylast

Features

  • Simple public interface.
  • Access to all the data exposed by the Last.fm web services.
  • Scrobbling support.
  • Full object-oriented design.
  • Proxy support.
  • Internal caching support for some web services calls (disabled by default).
  • Support for other API-compatible networks like Libre.fm.
  • Export your scrobbles and loved tracks to JSON Lines, from Python or the command line.

Getting started

Here's some simple code example to get you started. In order to create any object from pyLast, you need a Network object which represents a social music network that is Last.fm or any other API-compatible one. You can obtain a pre-configured one for Last.fm and use it as follows:

import pylast

# You have to have your own unique two values for API_KEY and API_SECRET
# Obtain yours from https://www.last.fm/api/account/create for Last.fm
API_KEY = "b25b959554ed76058ac220b7b2e0a026"  # this is a sample key
API_SECRET = "425b55975eed76058ac220b7b4e8a054"

# In order to perform a write operation you need to authenticate yourself
username = "your_user_name"
password_hash = pylast.md5("your_password")

network = pylast.LastFMNetwork(
    api_key=API_KEY,
    api_secret=API_SECRET,
    username=username,
    password_hash=password_hash,
)

Alternatively, instead of creating network with a username and password, you can authenticate with a session key:

import pylast

SESSION_KEY_FILE = os.path.join(os.path.expanduser("~"), ".session_key")
network = pylast.LastFMNetwork(API_KEY, API_SECRET)
if not os.path.exists(SESSION_KEY_FILE):
    skg = pylast.SessionKeyGenerator(network)
    url = skg.get_web_auth_url()

    print(f"Please authorize this script to access your account: {url}\n")
    import time
    import webbrowser

    webbrowser.open(url)

    while True:
        try:
            session_key = skg.get_web_auth_session_key(url)
            with open(SESSION_KEY_FILE, "w") as f:
                f.write(session_key)
            break
        except pylast.WSError:
            time.sleep(1)
else:
    session_key = open(SESSION_KEY_FILE).read()

network.session_key = session_key

And away we go:

# Now you can use that object everywhere
track = network.get_track("Iron Maiden", "The Nomad")
track.love()
track.add_tags(("awesome", "favorite"))

# Type help(pylast.LastFMNetwork) or help(pylast) in a Python interpreter
# to get more help about anything and see examples of how it works

More examples in hugovk/lastfm-tools and tests/.

Exporting your scrobbles

pyLast can export a user's complete listening history, with MusicBrainz IDs, to a JSON Lines file: one JSON object per line, easy to convert to anything else. You only need an API key, not a password, for public profiles.

From the command line:

export PYLAST_API_KEY=your_api_key
python -m pylast export your_username   # your_username.jsonl + your_username-loved.jsonl
python -m pylast export your_username --from 2024-01-01 --to 2025

Scrobbles are written newest first, a page at a time, so an interrupted export can be resumed by running the same command again: it continues from the oldest scrobble already in the file. Dates are Unix timestamps or ISO 8601, and dates without a timezone are UTC. See python -m pylast export --help for everything.

From Python:

import pylast
from pylast.export import export_scrobbles

network = pylast.LastFMNetwork(api_key=API_KEY)
network.enable_rate_limit()
user = network.get_user("your_username")

# Write everything to a file, resuming if the file already exists:
export_scrobbles(user, "your_username.jsonl")

# Or work with the records yourself; this streams one page at a time:
for scrobble in user.get_scrobbles():
    print(scrobble.datetime, scrobble.artist, scrobble.title, scrobble.track_mbid)

Each record has timestamp, artist, title, album, artist_mbid, track_mbid, album_mbid and url. user.get_loves() and export_loved() do the same for loved tracks. Transient API errors are retried with exponential backoff.

Testing

The tests/ directory contains integration and unit tests with Last.fm, and plenty of code examples.

For integration tests you need a test account at Last.fm that will become cluttered with test data, and an API key and secret. Either copy example_test_pylast.yaml to test_pylast.yaml and fill out the credentials, or set them as environment variables like:

export PYLAST_USERNAME=TODO_ENTER_YOURS_HERE
export PYLAST_PASSWORD_HASH=TODO_ENTER_YOURS_HERE
export PYLAST_API_KEY=TODO_ENTER_YOURS_HERE
export PYLAST_API_SECRET=TODO_ENTER_YOURS_HERE

To run all unit and integration tests:

python3 -m pip install -e ".[tests]"
pytest

Or run just one test case:

pytest -k test_scrobble

To run with coverage:

pytest -v --cov pylast --cov-report term-missing
coverage report # for command-line report
coverage html   # for HTML report
open htmlcov/index.html

Logging

To enable from your own code:

import logging
import pylast

logging.basicConfig(level=logging.INFO)


network = pylast.LastFMNetwork(...)

To enable from pytest:

pytest --log-cli-level info -k test_album_search_images

To also see data returned from the API, use level=logging.DEBUG or --log-cli-level debug instead.

Metadata

Release files for pylast 7.3.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 pylast 7.3.0
File Size Uploaded Provenance Actions
pylast-7.3.0.tar.gz 462.0 kB With provenance Details for pylast-7.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pylast 7.3.0
File Interpreter ABI Platform Actions
pylast-7.3.0-py3-none-any.whl Python 3 none any Details for pylast-7.3.0-py3-none-any.whl

Total release size: 498.9 kB

Release files / pylast-7.3.0.tar.gz

Download URL pylast-7.3.0.tar.gz
Size 462.0 kB
Tags Source
SHA-256 checksum
How to use checksums
06d8c124838e75bc8800d6df276add9c13b889a167678fc055957fcd2b35f444
BLAKE2b-256 checksum
How to use checksums
2d6618ff0216571154dd171af7418cd6a8a5a9085bea7ef707c5aff234010078
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / pylast-7.3.0-py3-none-any.whl

Download URL pylast-7.3.0-py3-none-any.whl
Size 36.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8172b5bbfc4fdc55312c2b4037e1021829050edf31ced403371352f3a04499d7
BLAKE2b-256 checksum
How to use checksums
c58369f771592ff90d71a42849cfcb17c0e85e3ac5f6cc9e6ae09b85dc479c72
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for pylast 7.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pylast-7.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

7.3.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page