Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time


This is the continuation of the official "Discogs API client for Python", which was deprecated by as of June 2020. We, the Joalla Team, think it is a very useful Python module and are continuing maintenance.

python3-discogs-client enables you to query the Discogs database ( through its REST-API for information on artists, releases, labels, users, Marketplace listings, and more. It also supports OAuth 1.0a authorization, which allows you to change user data such as profile information, collections and wantlists, inventory, and orders.

Find usage information on our documentation pages, ask for help, suggest features and help others in the discussion section of our github repo. If you'd like to contribute your code, you are welcome to submit a pull-request as described here.

There also is the long running thread "Continuation of the Python Discogs API Client" on the Discogs developer forum we use to announce releases and other news.

Coverage Status


Install the client from PyPI using your favorite package manager.

$ pip3 install python3-discogs-client


Instantiating the client object

>>> import discogs_client
>>> d = discogs_client.Client('ExampleApplication/0.1')

For more information, have a look at the quickstart section in our documentation pages.


There are two different authorization methods you can choose from depending on your requirements: User-token and OAuth authentication.

Note that Authorization is an optional feature of the Discogs API but a lot of basic functionality, like searching for releases, artists, etc. requires users being authenticated already.

User-token authentication

This is the quickest way to authenticate and become able to perform requests requiring authentication, such as search (see below).

For this, you'll need to generate a user-token from your developer settings on the Discogs website.

>>> d = discogs_client.Client('ExampleApplication/0.1', user_token="my_user_token")

Head to the authentication section in our docs to learn about the OAuth authentication method.

Fetching data

Use methods on the client to fetch objects. You can search for objects:

>>> results ='Stockholm By Night', type='release')
>>> results.pages
>>> artist = results[0].artists[0]
u'Persuader, The'

Or fetch them by ID:

>>> artist == d.artist(1)

You can drill down as far as you like.

>>> releases ='Bit Shifter', type='artist')[0].releases[1].\
...     versions[0].labels[0].releases
>>> len(releases)

Have a look at the searching and fetching data sections in our documentation pages.

Marketplace listing

Get listings/releases from a user's inventory (this does not require authentication)

>>> user = d.user('username')
>>> inventory = user.inventory
>>> inventory.count
>>> inventory.pages
>>> inventory.per_page = 100
>>> inventory.pages
>>> first_page =
>>> first_page[0]  # get the first listing on the page
<Listing 2314412455 'Bing Crosby - Der Bingle (10")'>
>>> first_listing.release
<Release 2604203 'Der Bingle'>

As an authenticated user you can add, edit and delete your own marketplace listings.

from discogs_client import Condition, Status, Sort
# Add new listing
    release=15246519,                       # Also accepts Release object
    condition=Condition.MINT,               # condition set to 'Mint (M)'
    status=Status.DRAFT,                    # status set to 'Draft'
    sleeve_condition=Condition.NEAR_MINT    # sleeve condition set to 'Near Mint (NM or M-)'

To learn how to update your inventory and delete listings, have a look at the marketplace listing section in our docs.

For more information


  1. Fork this repo
  2. Create a feature branch
  3. Open a pull-request

Some more helpful information on this topic can be found in the contribution section in our docs.