Skip to main content

deezer-python-gql

Async typed Python client for Deezer's Pipe GraphQL API.

Built with ariadne-codegen — all client methods and response models are generated from the GraphQL schema and .graphql query files.

Installation

uv add deezer-python-gql

Quick Start

import asyncio

from deezer_python_gql import DeezerGQLClient


async def main():
    client = DeezerGQLClient(arl="YOUR_ARL_COOKIE")

    # Current user
    me = await client.get_me()
    print(me)

    # Track with media URLs, lyrics, and contributors
    track = await client.get_track(track_id="3135556")
    print(track.title, track.duration)

    # Album with paginated track list
    album = await client.get_album(album_id="302127")
    print(album.display_title, album.tracks_count)

    # Artist with top tracks and discography
    artist = await client.get_artist(artist_id="27")
    print(artist.name, artist.fans_count)

    # Playlist with tracks
    playlist = await client.get_playlist(playlist_id="53362031")
    print(playlist.title, playlist.estimated_tracks_count)

    # Unified search across all entity types
    results = await client.search(query="Daft Punk")
    print(len(results.tracks.edges), "tracks found")


asyncio.run(main())

Available Queries

Content Retrieval

Method Description
get_me() Current authenticated user
get_track(track_id) Full track details — ISRC, media tokens, lyrics, contributors
get_album(album_id) Album with cover, label, paginated tracks, fallback
get_artist(artist_id) Artist with bio, top tracks, albums (ordered by release date)
get_playlist(playlist_id) Playlist with owner, picture, paginated tracks
get_livestream(livestream_id) Livestream (radio station) with streaming URLs and codec info
get_podcast(podcast_id) Podcast with paginated episodes and rights info
get_podcast_episode(podcast_episode_id) Single episode with media URL, codec, and parent podcast ref
get_audiobook(audiobook_id) Audiobook with paginated chapters, contributors, and fallback
get_audiobook_chapter(audiobook_chapter_id) Chapter with media token, estimated sizes, and streaming rights

Search & Discovery

Method Description
search(query, ...) Unified search across tracks, albums, artists, playlists, podcasts, livestreams
search_flows(query) Discover all available Deezer flows via search
get_similar_tracks(track_id, nb) Recommended tracks based on a given track
get_artist_mix(artist_ids, limit) Track mix blended from given artists
get_track_mix(track_ids, limit) Track mix blended around given tracks
get_flow() User's default Flow with tracks
get_flow_batch() 4 batches of Flow tracks in one request (via GraphQL aliases)
get_flow_configs(moods_first, genres_first) Mood & genre flow config lists for discovery
get_flow_config_tracks(flow_config_id) Tracks for a specific mood/genre flow config
get_made_for_me(first) "Made For You" SmartTracklist & Flow items
get_smart_tracklist(smart_tracklist_id, first) Smart tracklist with paginated tracks
get_charts(country_code, ...) Country charts — tracks, albums, artists, playlists
get_recommendations(playlists_first, ...) Personalized recommendations across categories
get_recently_played(first) Recently played mixed content (albums, playlists, artists...)
get_user_charts() Personal top tracks, artists, and albums

Library & Favorites

Method Description
get_favorite_artists(first, after) Paginated favorite artists
get_favorite_albums(first, after) Paginated favorite albums
get_favorite_tracks(first, after) Paginated favorite tracks
get_favorite_playlists(first, after) Paginated favorite playlists
get_favorite_podcasts(first, after) Paginated favorite podcasts
get_favorite_audiobooks() Favorite audiobook IDs with dates (via deprecated endpoint)
get_podcast_episode_bookmarks(first, after) Bookmarked podcast episodes with playback position
get_user_playlists(first, after) User's own playlists (not just favorites)
get_personal_tracks(first, after) User's uploaded/personal tracks (restricted access)

Music Together (Collaborative Playlists)

Method Description
get_music_together_groups(first) User's Music Together groups
get_music_together_group(group_id, mood) Single group with members, suggested & curated tracklists
get_music_together_affinity(group_id) Group member affinity scores and discovery content

Available Mutations

Favorites Management

Method Description
add_artist_to_favorite(artist_id) Add artist to favorites
remove_artist_from_favorite(artist_id) Remove artist from favorites
add_album_to_favorite(album_id) Add album to favorites
remove_album_from_favorite(album_id) Remove album from favorites
add_track_to_favorite(track_id) Add track to favorites
remove_track_from_favorite(track_id) Remove track from favorites
add_playlist_to_favorite(playlist_id) Add playlist to favorites
remove_playlist_from_favorite(playlist_id) Remove playlist from favorites
add_podcast_to_favorite(podcast_id) Add podcast to favorites
remove_podcast_from_favorite(podcast_id) Remove podcast from favorites
add_audiobook_to_favorite(audiobook_id) Add audiobook to favorites (deprecated but functional)
remove_audiobook_from_favorite(audiobook_id) Remove audiobook from favorites (deprecated but functional)

Playlist Management

Method Description
create_playlist(title, ...) Create a new playlist
update_playlist(playlist_id, ...) Update playlist title, description, or visibility
delete_playlist(playlist_id) Delete a playlist
add_tracks_to_playlist(playlist_id, track_ids) Add tracks to a playlist
remove_tracks_from_playlist(playlist_id, ...) Remove tracks from a playlist

Podcast Episode Management

Method Description
bookmark_podcast_episode(episode_id, offset) Bookmark episode with playback position (seconds)
unbookmark_podcast_episode(episode_id) Remove bookmark from episode
mark_as_played_podcast_episode(episode_id) Mark episode as played
mark_as_not_played_podcast_episode(episode_id) Mark episode as not played

Music Together

Method Description
music_together_create_group(name, ...) Create a new Music Together group
music_together_join_group(group_id) Join an existing group
music_together_leave_group(group_id) Leave a group
music_together_refresh_suggested_tracklist(...) Refresh the suggested tracklist for a group
music_together_update_group_settings(...) Update group settings (name, family mode)
music_together_generate_group_name() Generate a random group name

Utilities

Method Description
check_audiobook_ids(album_ids) Batch-check which album IDs are audiobooks (aliased queries, chunked at 50 IDs)

All methods return fully-typed Pydantic models generated from the GraphQL schema.

Development

Requires Python 3.12+ and uv.

# Install all dependencies (including codegen tooling)
make setup

# Re-generate the typed client from schema + queries
make generate

# Run linters and type checks
make lint

# Run tests
make test

Adding a new query

  1. Create a .graphql file in queries/.
  2. Run make generate to produce the typed client method and response models.
  3. Add tests in tests/.

Exploring the API

To run ad-hoc GraphQL queries against the live Pipe API during development:

  1. Create a .env file (already gitignored) with your ARL cookie:

    echo 'DEEZER_ARL=your_arl_cookie_value' > .env
    
  2. Run queries:

    # Run a .graphql file
    uv run python scripts/explore.py queries/get_me.graphql
    
    # Run an inline query
    uv run python scripts/explore.py -q '{ me { id } }'
    
    # With variables
    uv run python scripts/explore.py -q 'query($id: String!) { track(trackId: $id) { title } }' \
        -v '{"id": "3135556"}'
    
    # Via make
    make explore Q=queries/get_me.graphql
    

The script handles JWT auth automatically — no manual token management needed.

Authentication

The Pipe API uses short-lived JWTs obtained from an ARL cookie. The base client handles token acquisition and refresh automatically — you only need to supply a valid ARL value.

An external aiohttp.ClientSession may be shared by clients for different Deezer accounts. Each client keeps Deezer's response cookies locally and masks cookies from the shared session jar, so authentication state cannot cross between those accounts.

If the ARL is rejected (bad or expired), the client raises GraphQLClientAuthError — catch it to prompt for a new ARL instead of retrying. Transient server errors raise GraphQLClientHttpError instead.

License

Apache-2.0

Metadata

Release files for deezer-python-gql 0.17.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for deezer-python-gql 0.17.2
File Size Uploaded Provenance Actions
deezer_python_gql-0.17.2.tar.gz 66.0 kB With provenance Details for deezer_python_gql-0.17.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for deezer-python-gql 0.17.2
File Interpreter ABI Platform Actions
deezer_python_gql-0.17.2-py3-none-any.whl Python 3 none any Details for deezer_python_gql-0.17.2-py3-none-any.whl

Total release size: 143.9 kB

Release files / deezer_python_gql-0.17.2.tar.gz

Download URL deezer_python_gql-0.17.2.tar.gz
Size 66.0 kB
Tags Source
SHA-256 checksum
How to use checksums
95e55a42b6cbccfaf479e56b05be20db7862c1c604b2522393ef8444c29bb3aa
BLAKE2b-256 checksum
How to use checksums
c4fb12e08a81d357b03938692e934d93c50363ae16902e675be73b41aeb6869d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Sep 4, 2026.

Transparency log

Release files / deezer_python_gql-0.17.2-py3-none-any.whl

Download URL deezer_python_gql-0.17.2-py3-none-any.whl
Size 77.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4880c8b9f6e5924158eb97f2f5681e80e496dbd519b386587c26510d89eb9135
BLAKE2b-256 checksum
How to use checksums
bfe7ed11207e55962c027805c9a5c13d5e6f36d152d04fbefae81f502b4e5dab
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Sep 4, 2026.

Transparency log

Security for deezer-python-gql 0.17.2

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 deezer_python_gql-0.17.2.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 Sep 4, 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

0.17.2 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