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
PUIDandPGIDto the numeric user and group that should own Listenarr's files. The entrypoint prepares/app/configbefore switching users; the audiobook and download bind mounts must already have suitable permissions for that user. PGIDdefaults toPUIDwhen omitted.GIDis accepted as an alias forPGID, andUMASK_SETas an alias forUMASK. The default mask is022.canaryfollows the latest canary prerelease. Usecanary-X.Y.Zto pin a published canary version. Check the release list for available builds and assets rather than assuming a stable release exists.LISTENARR_PUBLIC_URLis 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
/downloadsand/audiobooksmounts can prevent hardlinks even when the host paths share a disk. For hardlinks, consider one shared mount such as/srv/media:/data, with/data/downloadsand/data/audiobooksbeneath 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.xor later. - For the Discord bot, set
LISTENARR_PUBLIC_URLto 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.jsonand 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.