How to Self-Host Deemix with Docker Compose

What Is Deemix?

Want to build a local music library from Deezer without manually downloading tracks one at a time? Deemix is a self-hosted web application that downloads music from Deezer’s catalog, preserving metadata, album art, and lyrics. It supports FLAC, MP3 320, and other quality tiers depending on your Deezer subscription level.

Deemix is a community revival of the original project by RemixDev. The current maintained fork runs as a Docker container with a web UI for searching, browsing, and batch-downloading tracks, albums, and playlists.

Feature	Details
License	GPL-3.0
Source	Deezer catalog
Quality options	MP3 128, MP3 320, FLAC
Metadata	Full (artist, album, track, lyrics, album art)
Batch downloads	Albums, playlists, artist discographies
Lidarr integration	Via Deemix as a download client
Web UI	Vue.js interface
Architecture	amd64

Legal note: Deemix requires a valid Deezer account. FLAC downloads require Deezer HiFi ($14.99/month). Downloading copyrighted music may violate Deezer’s terms of service and local copyright laws. Use responsibly and in accordance with applicable laws.

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (Docker Compose Basics)
• 256 MB of free RAM
• A Deezer account (free or premium)
• Storage for your music library

Docker Compose Configuration

Create a directory for Deemix:

mkdir -p /opt/deemix/{config,downloads}

Create /opt/deemix/docker-compose.yml:

services:
  deemix:
    image: ghcr.io/bambanah/deemix:0.4.3
    container_name: deemix
    restart: unless-stopped
    ports:
      - "6595:6595"
    volumes:
      - ./config:/config
      - ./downloads:/downloads
    environment:
      # User/group ID for file ownership (match your music directory)
      PUID: 1000
      PGID: 1000
      # Server settings
      DEEMIX_SERVER_PORT: 6595
      DEEMIX_HOST: "0.0.0.0"
      # Single-user mode (no login required)
      DEEMIX_SINGLE_USER: "true"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:6595"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

Start the container:

cd /opt/deemix && docker compose up -d

Initial Setup

1. Open http://your-server-ip:6595 in your browser
2. Click the settings icon (gear) in the sidebar
3. Log in with your Deezer account:
   • Go to deezer.com, log in, and find your ARL token in browser cookies (F12 → Application → Cookies → arl)
   • Paste the ARL token into Deemix’s login field
4. Configure your download directory (default: /downloads)
5. Set your preferred audio quality

Finding Your Deezer ARL Token

The ARL (Authentication Request Listener) token is how Deemix authenticates with Deezer’s API:

1. Log in to deezer.com in your browser
2. Open browser developer tools (F12)
3. Go to Application → Cookies → https://www.deezer.com
4. Find the cookie named arl
5. Copy its value (a long alphanumeric string)

ARL tokens expire periodically (typically every 3-6 months). When downloads start failing with authentication errors, generate a new ARL by logging in again.

Configuration

Download Quality

Quality	Bitrate	File Size (per track)	Requires
MP3 128	128 kbps	~3-4 MB	Free account
MP3 320	320 kbps	~7-10 MB	Premium account
FLAC	~1,411 kbps	~25-40 MB	HiFi account

Settings → Download quality. Deemix automatically falls back to the next available quality if your account doesn’t support the selected tier.

Download Path Template

Customize how files are organized on disk. Settings → Download path template:

%artist%/%album% (%year%)/%number% - %title%

This creates: Artist Name/Album Name (2025)/01 - Track Title.flac

Common templates:

Template	Result
%artist%/%album%/%number% - %title%	Artist/Album/01 - Track.flac
%artist%/%album% [%quality%]/%number% - %title%	Artist/Album [FLAC]/01 - Track.flac
%albumartist%/%album% (%year%)/%number% - %title%	Uses album artist for compilations

Metadata and Artwork

Deemix embeds full metadata by default:

• Artist, album artist, album, track title, track number
• Year, genre, label, ISRC
• Lyrics (synced, if available)
• Album artwork (up to 3000×3000 pixels)

Settings → Embedded art size: set to 1200 for a good balance between quality and file size. 3000 is overkill for most use cases and inflates file sizes.

Advanced Configuration

Lidarr Integration

Deemix can act as a download client for Lidarr, automating music library management:

1. In Lidarr → Settings → Download Clients → Add → Deemix
2. Host: deemix (or the container IP)
3. Port: 6595
4. Category: leave default

Lidarr monitors for new releases from artists in your library and sends download requests to Deemix automatically.

Spotify Playlist Import

Deemix can convert Spotify playlists to Deezer equivalents and download them:

1. In the Deemix search bar, paste a Spotify playlist URL
2. Deemix matches tracks to Deezer’s catalog
3. Unmatched tracks are skipped (shown in the download log)

Match rates are typically 90-95% for popular music. Niche or region-specific tracks may not have Deezer equivalents.

Multi-User Mode

Disable single-user mode for shared installations:

environment:
  DEEMIX_SINGLE_USER: "false"

Each user logs in with their own Deezer ARL token. Downloads are attributed to the user who initiated them.

Reverse Proxy

For remote access through a reverse proxy, configure your proxy to forward to port 6595:

location / {
    proxy_pass http://localhost:6595;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

See our Reverse Proxy Setup guide for complete proxy configuration.

Backup

The only critical data is in /config:

• config.json — your settings and preferences
• Login session data (ARL token)

Your downloaded music in /downloads should be backed up as part of your regular media backup strategy.

# Backup config
cp -r /opt/deemix/config /backup/deemix-config-$(date +%Y%m%d)

See our Backup Strategy guide.

Troubleshooting

Downloads fail with “No space left on device”

Symptom: Downloads start but fail partway through.

Fix: Check available disk space on the volume where /downloads is mounted:

df -h /opt/deemix/downloads

FLAC albums average 300-500 MB. A 1,000-album library needs 300-500 GB.

ARL token expired

Symptom: All downloads fail with authentication errors. The web UI shows “Not logged in.”

Fix: ARL tokens expire after 3-6 months. Generate a new one:

1. Log in to deezer.com in a browser
2. Extract the new arl cookie value
3. Paste it into Deemix settings

Downloads stuck at 0%

Symptom: Downloads queue but never progress.

Fix: Deezer may be rate-limiting your account or IP. Wait 10-15 minutes and retry. If persistent, your ARL may be invalidated — regenerate it. Avoid downloading hundreds of albums simultaneously — batch in groups of 10-20.

File permissions wrong on downloads

Symptom: Downloaded files are owned by root or an unexpected user.

Fix: Set PUID and PGID in your Docker Compose to match the user that should own the files:

# Find your user's ID
id $(whoami)
# Use the uid and gid values in PUID and PGID

Metadata missing or incorrect

Symptom: Track titles, artists, or album art are wrong or blank.

Fix: Deemix uses Deezer’s metadata database. If metadata is wrong in Deezer, it’ll be wrong in your download. For corrections, use a local tagger like MusicBrainz Picard after downloading.

Resource Requirements

Metric	Idle	Active Downloads
RAM	100-150 MB	200-300 MB
CPU	Minimal	Low-Medium (during FLAC downloads)
Disk	20 MB (app)	Depends on library size
Network	None	1-10 Mbps per concurrent download

Deemix is lightweight. It runs comfortably alongside other services on any hardware capable of running Docker.

Verdict

For building a local music library from Deezer’s catalog, Deemix is the most streamlined tool available. The web UI is clean, metadata handling is excellent, and Lidarr integration turns it into an automated library manager. If you have a Deezer subscription and want local copies of your music, this is the tool.

The caveat: Deemix depends entirely on Deezer’s API and your ARL token. Deezer can (and has) changed their API to break third-party tools. If long-term reliability matters more than convenience, consider purchasing music from Bandcamp or ripping your own CDs — those files never depend on a third-party service staying compatible.

FAQ

Do I need a paid Deezer account? A free account works for MP3 128 kbps downloads. Premium ($10.99/month) unlocks MP3 320. HiFi ($14.99/month) unlocks FLAC. The quality difference between 128 and 320 kbps is substantial — premium is worth it if you care about audio quality.

Is Deemix legal? Deemix itself is open-source software. Whether using it to download music is legal depends on your jurisdiction and how you use the downloaded files. Downloading music you’ve paid for through a Deezer subscription for personal offline use occupies a gray area. Distributing downloaded music is unambiguously illegal in most jurisdictions.

Can I use Deemix with Spotify instead of Deezer? No. Deemix only works with Deezer’s API. You can import Spotify playlists (Deemix matches tracks to Deezer equivalents), but the actual downloads come from Deezer.

How does Deemix compare to Lidarr alone? Lidarr is a library manager that needs a download source. Deemix is a download source. They work together: Lidarr decides what to download, Deemix fetches it from Deezer. Lidarr can also use Usenet or torrent indexers as download sources.

Related

• Best Self-Hosted Music Streaming
• How to Self-Host Lidarr
• How to Self-Host Navidrome
• Navidrome vs Funkwhale
• Self-Hosted Alternatives to Spotify
• Self-Hosted Alternatives to Apple Music
• Music Server Hardware Guide
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy