discogs-sdk

discogs-sdk is a modern Python client for the Discogs API covering every documented v2 endpoint, with a fluent chainable syntax and built-in response caching.

from discogs_sdk import Discogs

with Discogs() as client:
    release = client.releases.get(352665)
    print(f"{release.title} ({release.year})")

    for result in client.search(query="Nine Inch Nails", type="artist"):
        print(result.title)

Installation

pip install discogs-sdk
# or
uv add discogs-sdk

Requires Python 3.10+.

Features

• Complete Endpoint Coverage — Every route in the Discogs API v2 documentation
• Fluent API — Chain sub-resources naturally: client.releases.get(id).rating.get()
• Lazy Loading — No HTTP calls until you actually need the data
• Effortless Pagination — Browse results without managing pages or offsets
• Rate Limit Aware — Bounded retries with Retry-After support
• Built-in Caching — Optional TTL-based caching reduces API calls
• Flexible Auth — Supports personal tokens, consumer key/secret, or full OAuth 1.0a
• Type Safe — Get autocomplete and IDE support
• Async & Sync — Full support for both synchronous and asynchronous workflows

How it compares

The established alternative is python3-discogs-client. Both load data lazily, paginate automatically, support OAuth 1.0a and back off on HTTP 429, so the differences that matter are:

† No inventory export or upload, release ratings or have/want stats, collection fields, folder creation, contributions or submissions.

Quick start

Authentication

Set your personal access token from your Discogs developer settings as an environment variable:

export DISCOGS_TOKEN="your-token-here"

from discogs_sdk import Discogs

client = Discogs()  # reads DISCOGS_TOKEN from environment

You can also pass credentials explicitly:

client = Discogs(token="your-token-here")

The SDK supports three auth modes: personal token, consumer key/secret, and OAuth 1.0a. Exactly one mode is selected when the client is constructed, and only that mode's credentials are used. The precedence is:

1. An explicit token selects personal-token auth and overrides every environment credential.
2. Explicit OAuth access-token credentials select OAuth; any missing half may come from the matching DISCOGS_* variable, but an unrelated environment token never takes over.
3. Explicit consumer_key/consumer_secret select consumer auth, without borrowing environment access tokens.
4. With no auth arguments, the environment resolves the mode: DISCOGS_TOKEN, then a complete OAuth set, then DISCOGS_CONSUMER_KEY/DISCOGS_CONSUMER_SECRET, then unauthenticated.

An explicitly selected but incomplete credential set raises ValueError rather than quietly falling back to a different account or mode. See examples/authentication.py for the full OAuth flow.

[!TIP] Use a .env file with python-dotenv or direnv to avoid exporting tokens manually in every shell.

[!NOTE] Discogs allows 60 requests/minute authenticated and 25/minute unauthenticated, measured as a moving average over the last 60 seconds. The SDK does not pace your requests: it retries a rate-limited read a bounded number of times (max_retries, default 3), honouring Retry-After. Sustained traffic above the limit still needs pacing on your side, and you can still receive RateLimitError once the retries are exhausted.

[!WARNING] Mutations are not replayed. A POST, PUT or DELETE is retried only when the failure proves the request never reached the server, such as a refused connection. After a read timeout or a 5xx the change may already have been committed, so the SDK raises instead of sending it again — the remote outcome is genuinely unknown and only you can decide how to reconcile it.

Fetching resources

# Releases, artists, masters, labels
release = client.releases.get(352665)
print(release.title)  # lazy — HTTP fires here → "The Downward Spiral"

artist = client.artists.get(3857)
print(artist.name)  # "Nine Inch Nails"

master = client.masters.get(3719)
label = client.labels.get(647)

Search

for result in client.search(query="Pretty Hate Machine", type="release", year="1989"):
    print(f"[{result.type}] {result.title}")
    # [release] Nine Inch Nails - Pretty Hate Machine

Sub-resources

# Community rating
rating = client.releases.get(352665).rating.get()
print(f"Average: {rating.rating.average}")  # Average: 4.49

# Artist releases with sorting
for rel in client.artists.get(3857).releases.list(sort="year", sort_order="desc"):
    print(f"{rel.title} ({rel.year})")

# Master versions with filters
for v in client.masters.get(3719).versions.list(format="Vinyl", country="US"):
    print(f"{v.title} [{v.format}]")

Async usage

import asyncio
from discogs_sdk import AsyncDiscogs


async def main():
    async with AsyncDiscogs() as client:  # reads DISCOGS_TOKEN from environment
        # Must await lazy resources in async mode
        release = await client.releases.get(352665)
        print(release.title)

        # Async iteration for paginated results
        async for result in client.search(query="Nine Inch Nails"):
            print(result.title)


asyncio.run(main())

Collection

user = client.users.get("your_username")

# Folders
folders = user.collection.folders.list()
user.collection.folders.create(name="Industrial")

# Browse folder contents
for item in user.collection.folders.get(0).releases.list(sort="added"):
    print(item.basic_information.title)

# Add a release. The response identifies the copy you just created, which is
# how you tell it apart from copies of the same release you already own.
created = user.collection.folders.get(1).releases.create(release_id=352665)

# Deep chaining: folder -> release -> instance -> fields
instances = user.collection.folders.get(1).releases.get(352665).instances
instances.get(created.instance_id).fields.update(field_id=1, value="Signed copy")

# Collection value
value = user.collection.value.get()
print(f"Median: {value.median}, Maximum: {value.maximum}")

# Wantlist — the add takes only the release id; Discogs drops notes and ratings
# sent to it, so they go in the update call
user.wantlist.create(release_id=352665)
user.wantlist.update(352665, notes="Original pressing", rating=4)
for want in user.wantlist.list():
    print(want.basic_information.title)

Marketplace

# Listings
listing = client.marketplace.listings.get(123456789)
new = client.marketplace.listings.create(
    release_id=352665,
    condition="Very Good Plus (VG+)",
    price=25.00,
)
client.marketplace.listings.update(new.id, price=22.50)
client.marketplace.listings.delete(new.id)

# Orders
for order in client.marketplace.orders.list(status="Payment Received"):
    print(f"Order {order.id}: {order.status}")

# Fee lookup
fee = client.marketplace.fee.get(price=25.00, currency="USD")

Error handling

from discogs_sdk import NotFoundError, RateLimitError, AuthenticationError

try:
    release = client.releases.get(999999999)
    _ = release.title
except NotFoundError:
    print("Not found")
except RateLimitError as exc:
    print(f"Rate limited, retry after {exc.retry_after}s")
except AuthenticationError:
    print("Bad credentials")

The full exception hierarchy:

DiscogsError
├── DiscogsConnectionError
└── DiscogsAPIError
    ├── AuthenticationError  (401)
    ├── ForbiddenError       (403)
    ├── NotFoundError        (404)
    ├── ValidationError      (422)
    └── RateLimitError       (429)

Examples

The examples/ directory has runnable scripts for every feature:

• quickstart.py — first requests, lazy loading, search
• authentication.py — all auth modes including OAuth 1.0a
• database.py — releases, artists, masters, labels, search
• marketplace.py — listings, orders, fees, inventory
• collection.py — folders, instances, fields, wantlist
• async_usage.py — async client with await and async for
• advanced.py — error handling, caching, custom HTTP clients, exports

Configuration

See Authentication for how a credential mode is selected.

Caching

Only successful GET/HEAD responses are cached. Entries are keyed by method, fully resolved URL, the effective Accept representation, and a non-reversible digest of the selected mode's credentials, so two clients sharing one cache — or one SQLite directory — never serve each other's private responses, and unauthenticated traffic gets its own namespace. No token or secret is stored in a key.

client.no_cache() bypasses the cache for the current execution context. Scopes nest, the previous state is restored even when the block raises, and concurrent tasks or threads each carry their own state:

with client.no_cache():
    fresh = client.releases.get(352665).title  # always hits the API

Custom HTTP clients

An injected http_client must be an httpx2 client — the SDK is built on httpx2, Pydantic's maintained continuation of httpx. It owns its transport configuration and its lifecycle: client.close() never closes it. SDK credentials, User-Agent and media type are still applied per request, so they describe the request without mutating your client's defaults, and its own httpx2.Auth cannot replace credentials you gave the SDK. When the SDK has no credentials of its own, your client's authentication is preserved and its responses are not cached, because the SDK cannot tell whose account they belong to.

Field naming

Model fields use clean Python names. Where the Discogs API uses inconsistent or cryptic keys, the SDK provides a readable alias while still accepting the raw API name during deserialization:

Both names work as attributes, so you can use whichever you prefer:

release = client.releases.get(352665)  # The Downward Spiral
print(release.extra_artists)  # Python name
print(release.extraartists)  # API name — same value

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

License

discogs-sdk is licensed under the Apache License 2.0.