Skip to main content

Installation

Listenarr supports Docker, self-contained executables, and source-based development workflows. For most users, Docker is the cleanest production setup.

Docker​

Docker is the recommended deployment method for production.

docker run -d \
--name listenarr \
-p 4545:4545 \
-e PUID=1000 \
-e PGID=1000 \
-e UMASK=022 \
-e LISTENARR_PUBLIC_URL=https://your-domain.com \
-v listenarr_data:/app/config \
-v /path/to/audiobooks:/audiobooks \
-v /path/to/downloads:/downloads \
ghcr.io/listenarrs/listenarr:canary

The web app is available at http://localhost:4545.

What the mounts are for​

  • /app/config: persistent config and database storage
  • /audiobooks: optional library mount for root folders
  • /downloads: optional mount so Listenarr can access completed downloads directly

If you use Docker, enter the container paths in Listenarr. For example, if you mount /srv/audiobooks:/audiobooks, configure the root folder as /audiobooks, not /srv/audiobooks.

Docker Compose​

services:
listenarr:
image: ghcr.io/listenarrs/listenarr:canary
ports:
- "4545:4545"
environment:
- PUID=1000
- PGID=1000
- UMASK=022
- LISTENARR_LOG_LEVEL=Information
- LISTENARR_PUBLIC_URL=https://your-domain.com
volumes:
- listenarr_data:/app/config
- /path/to/audiobooks:/audiobooks
- /path/to/downloads:/downloads
restart: unless-stopped

volumes:
listenarr_data:

Docker notes​

  • Set PUID and PGID to the numeric user and group that should own Listenarr's files. The entrypoint prepares /app/config before switching users; the audiobook and download bind mounts must already have suitable permissions for that user.
  • PGID defaults to PUID when omitted. GID is accepted as an alias for PGID, and UMASK_SET as an alias for UMASK. The default mask is 022.
  • canary follows the latest canary prerelease. Use canary-X.Y.Z to pin a published canary version. Check the release list for available builds and assets rather than assuming a stable release exists.
  • LISTENARR_PUBLIC_URL is optional for the core app, but strongly recommended if you plan to use the Discord bot.
  • If your download client runs in another container and uses different mount paths, you will likely need remote path mappings in Listenarr.
  • Hardlinks need a shared filesystem as seen inside the container. Separate /downloads and /audiobooks mounts can prevent hardlinks even when the host paths share a disk. For hardlinks, consider one shared mount such as /srv/media:/data, with /data/downloads and /data/audiobooks beneath it, and use those paths consistently in both applications.

Self-contained executables​

Choose an archive from the Listenarr releases page, extract it, then launch the platform-specific binary. Current canary releases provide Linux x64 and Windows x64 archives; inspect the assets on your chosen release before downloading.

The directories below are example extraction locations; actual archive names include the version and commit.

Windows​

cd .\listenarr-win-x64
.\Listenarr.Api.exe

Linux​

cd ./listenarr-linux-x64
chmod +x Listenarr.Api
./Listenarr.Api

macOS​

Current canary releases do not include a macOS archive. Build from source, or use a release that explicitly provides the matching macOS asset. For a source build:

dotnet publish listenarr.api/Listenarr.Api.csproj -c Release -r osx-x64 --self-contained -o ./publish-macos
./publish-macos/Listenarr.Api

Use osx-arm64 instead of osx-x64 for Apple Silicon. Source builds require the SDK and Node.js prerequisites below.

By default, Listenarr serves on http://localhost:4545.

Executable prerequisites​

  • The releases are self-contained, so you do not need to install .NET separately for the normal executable packages.
  • If you plan to use Discord bot functionality outside Docker, install Node.js 24.x or later.
  • For the Discord bot, set LISTENARR_PUBLIC_URL to a URL reachable from the bot process. Use your real external URL when public links are needed.

Override the port​

You can change the listener URL at startup:

./Listenarr.Api --urls "http://localhost:5656"

Build from source​

If you want to run the full development stack locally:

  • Install the .NET 10 SDK selected by the repository's global.json and Node.js 24 or later with npm.
  • Clone Listenarr and run these commands from its repository root.
npm run install:all
npm run dev

That starts the API on http://localhost:4545 and the web frontend on http://localhost:5173.

Next​

Continue to First run to configure root folders, quality profiles, download clients, indexers, and the main settings.