Skip to content


Folders and files

Last commit message
Last commit date

Latest commit


Repository files navigation

Music Downloader ๐ŸŽถ ๐ŸŽง ๐Ÿ’ƒ ๐Ÿฆ„

tests latest tag Python 3.6 pypi-version pypi-downloads


  • download songs, albums, public playlists from (account is required, free plan is enough)
  • download Spotify playlists (by parsing the Spotify website and download the songs from Deezer)
  • download as zip file (including m3u8 playlist file)
  • 320 kbit/s (currently only 128 kbit/s, see this issue) mp3s with ID3-Tags and album cover
  • download songs via yt-dlp
  • KISS (keep it simple and stupid) front end
  • MPD integration (use it on a Raspberry Pi!)
  • simple REST api
  • proxy support (https/socks5)

How to use it

There is a settings file template called settings.ini.example. You can specify the download directory with download_dir. Pressing the download button only downloads the song/album/playlist. If you set use_mpd=True in the settings.ini the backend will connect to mpd (localhost:6600) and update the music database. Pressing the play button will download the music. If use_mpd=True is set the mpd database will be updated and the song/album/playlist will be added to the playlist. In settings.ini music_dir should be the music root location of mpd. The download_dir must be a subdirectory of music_dir.

As Deezer sometimes requires a captcha to login the auto login features was removed. Instead you have to manually insert a valid Deezer cookie to the settings.ini. The relevant cookie is the arl cookie. Important: The ARL cookie must be of a non-premium account!

kmille@linbox:deezer-downloader poetry run deezer-downloader --help
usage: deezer-downloader [-h] [-v] [-t] [-c CONFIG]

Download music from Deezer with a nice front end

  -h, --help            show this help message and exit
  -v, --version         show version and exit
  -t, --show-config-template
                        show config template. At least you have to insert the ARL cookie
  -c CONFIG, --config CONFIG
                        config file - if not supplied, the following directories are considered looking for deezer-downloader.ini: current working directory, XDG_CONFIG_HOME environment variable, ~/.config, /etc)

kmille@linbox:deezer-downloader poetry run deezer-downloader --config settings.ini
Starting Threadpool
/home/kmille/.cache/pypoetry/virtualenvs/deezer-downloader-NFDPq16k-py3.11/lib/python3.11/site-packages/ UserWarning: You are using the giphy public api key. This should be used for testing only and may be deactivated in the future. See
  warnings.warn('You are using the giphy public api key. This '
Worker 0 is waiting for a task
Worker 1 is waiting for a task
Worker 2 is waiting for a task
Worker 3 is waiting for a task
Worker 0 is now working on task: {'track_id': 8086130, 'add_to_playlist': False}
Downloading 'Adele - Set Fire to the Rain.mp3'
Dowload finished: /tmp/deezer-downloader/songs/Adele - Set Fire to the Rain.mp3
Setting state to mission accomplished to worker 0
worker 0 is done with task: {'track_id': 8086130, 'add_to_playlist': False} (state=mission accomplished)

How to get it up and running

with pip

You can run pip install --user deezer-downloader. Then you can run ~/.local/bin/deezer-downloader --help

with Docker

You can use the Docker image hosted on Login into your free Deezer account and grab the arl cookie. Then:

mkdir downloads
sudo docker run -p 5000:5000 --volume $(pwd)/downloads/:/mnt/deezer-downloader --env DEEZER_COOKIE_ARL=changeme kmille2/deezer-downloader:latest 
xdg-open http://localhost:5000

with Vagrant

vagrant up
vagrant ssh
sudo vim /opt/deezer/settings.ini # insert your Deezer cookie
cd /opt/deezer && sudo poetry run deezer-downloader --config settings.ini

# On the host:
xdg-open http://localhost:5000 # view frontend in the browser
ncmpcpp -h # try the mpd client

as a service

We use it with nginx and ympd as mpd frontend

  • / goes to ympd
  • /d/ goes to the downloader

The deployment directory contains a systemd unit file and a nginx vhost config file. There is also a patch to add a link to the ympd frontend. The debug tab will show you the debug output of the app.Shortcuts

If you want to debug or build it from source: there is a docker-compose file in the docker directory. The docker/downloads directory is mounted into the container and will be used as download directory. You have to check the permissions of the docker/downloads directory as docker mounts it with the same owner/group/permissions as on the host. The deezer user in the docker container has uid 1000. If you also have the uid 1000 then there should be no problem. For debugging: sudo docker-compose build --force-rm && sudo docker-compose up

developer setup (tested on Ubuntu Jammy)

  sudo apt-get update -q
  sudo apt-get install -qy vim tmux git ffmpeg

  # python3-poetry is too old (does not support groups ...)
  sudo apt-get install -qy python3-pip
  sudo pip install poetry
  git clone
  cd deezer-downloader
  poetry install
  poetry run deezer-downloader --show-config-template > settings.ini

  # enable yt-dlp
  sudo pip install yt-dlp
  sed -i 's,.*command = /usr/bin/yt-dlp.*,command = /usr/local/bin/yt-dlp,' settings.ini

  # enable mpd
  sudo apt-get install -yq mpd ncmpcpp
  sudo sed -i 's,^music_directory.*,music_directory         "/tmp/deezer-downloader",' /etc/mpd.conf
  sudo systemctl restart mpd
  sed -i 's/.*use_mpd = False.*/use_mpd = True/' settings.ini

  # 1) Adjust the Deezer cookie: vim settings.ini
  # 2) Run tests: DEEZER_DOWNLOADER_CONFIG_FILE=settings.ini poetry run pytest -v -s
  # 3) Run it: poetry run deezer-downloader --config settings.ini
  # 4) Try out: ncmpcpp -h && xdg-open http://localhost:5000
  # 5) Downloaded files are in /tmp/deezer-downloader

ctrl-m: focus search bar
Enter: serach for songs
Alt+Enter: search for albums
ctrl-b: go to / (this is where our ympd is)
ctrl-shift-[1-7] switch tabs

Some screenshots

Search for songs. You can listen to a 30 second preview in the browser.

Search for albums. You can download them as zip file.

List songs of an album.

Download songs with youtube-dl

Download a Spotify playlist.

Download a Deezer playlist.

ncmpcpp mpd client.


cd deezer-downloader
DEEZER_DOWNLOADER_CONFIG_FILE=settings.ini poetry run pytest -v -s
# if you don't setDEEZER_DOWNLOADER_CONFIG_FILE the default template file will be used. Some tests will fail because there is no valid arl_cookie.

Deployment with Ansible (including mpd and ympd) (almost always outdated)


Version 2.0.0 (27.03.2023)

  • use poetry as build system
  • build package and uploada to pypi
  • worker threads now "daemon threads" (they now just stop if you stop deezer-downloader)
  • update config template (remove http.debug)
  • update dependencies
  • switch to waitress (from gunicorn)

Version 1.3.3 (27.12.2021)

  • replace youtube-dl by yt-dl
  • update third party dependencies

Version 1.3.2 (26.11.2021)

  • fix broken deezer download functionality (#66, removes the ability to download flac quality)
  • update third party dependencies
  • update ubuntu base image for the docker container

Version 1.3.1 (21.01.2021)

  • allow to set download quality (flac|mp3) via environment variable DEEZER_FLAC_QUALITY (#43)

Version 1.3 (05.11.2020)

  • feature: download your favorite Deezer songs
  • automated tests with Github Actions
  • push Docker image to with Github Actions

Version 1.2 (01.11.2020)

  • breaking change: now use the arl cookie instead of the sid cookie. This cookie does not expire so we don't need the background thread that keeps the session alive
  • add support for flac as download format

Version 1.1 (13.05.2020)

  • thanks to luelista for the contribution!
  • play 30 second preview in browser
  • add Vagrantfile
  • show album cover in search results
  • use a threaded queue for download tasks
  • list album songs