Skip to Content
Listenarr

Listenarr

Automated audiobook and eBook collection management

Overview

Listenarr is an audiobook and eBook downloader in the *arr style — think Sonarr or Radarr, but for books. It monitors your favorite authors and titles, enriches metadata from Audible, Amazon, and OpenLibrary (covers, narrators, series data — all built in, no separate indexer app needed), and hands grabs to the download clients you already run: qBittorrent, Transmission, SABnzbd, or NZBGet.

Early, actively developed community project
Note

Listenarr is a community project — it is not part of the official Servarr suite. Upstream currently publishes canary pre-release builds only; no stable release exists yet. It works well and is moving fast, but expect the occasional rough edge and visible change between updates.

QuickBox Pro installs Listenarr per user as a self-contained build: the release ships everything in a single package, so there is no host runtime to install or maintain. The application code lives under /opt/username/Listenarr/, all of your data lives in one state tree under /home/username/.config/Listenarr/, and a per-user systemd service serves the UI at https://your-server/username/listenarr/ through the nginx reverse proxy — bound to localhost only, with nginx as the sole public entry point.


Key features

Audiobook & eBook Automation

Monitor authors and titles and grab new releases automatically in the familiar *arr workflow

Built-In Rich Metadata

Covers, narrators, and series data from Audible, Amazon, and OpenLibrary — no external indexer manager required

Download Client Integration

Hands grabs to qBittorrent, Transmission, SABnzbd, or NZBGet — your existing clients do the downloading

Quality & Format Profiles

Control preferred audiobook and eBook formats per title

Self-Contained Runtime

Ships as a single-file build with everything bundled — no host runtime to install, patch, or version-manage

Live UI Updates

Download progress, logs, and settings stream into the web UI in real time over WebSockets

Zero-Maintenance Storage

Library and settings live in a single SQLite database that migrates itself automatically on every update

Per-User Service

Isolated systemd unit listenarr@username with an auto-allocated port and loopback-only binding behind nginx

When to use it

Good fit

  • You want hands-off audiobook and eBook automation — monitor authors, grab new releases, sort and rename
  • You want audiobook-first metadata: narrators, series, and covers sourced from Audible
  • You already run qBittorrent, Transmission, SABnzbd, or NZBGet and want them put to work for books
  • You are looking for a successor to Readarr now that upstream has retired it

What you get

  • Install via qb install listenarr -u username — a fast binary install with no host runtime
  • Served at https://your-server/username/listenarr/ with WebSocket-powered live updates
  • Single per-user systemd service listenarr@username with auto-start on boot
  • If you need a settled, long-stable tool today, look at LazyLibrarian instead — Listenarr is young and pre-release

Installation

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find Listenarr under Media Management (browse the category or search), and click Install. The dashboard streams the install log live and Listenarr appears in your Application Control panel when it finishes. Reinstall and Remove are in the same Package Management panel. To update, use the amber Update badge on the Listenarr row in the App Dashboard.

The install downloads the newest upstream release, extracts it into the per-user install tree, patches the bundled web client for your personal URL path, and starts the service — no compile step, no runtime to provision.

What you see and can manage is gated by your account: admins manage any user’s apps; regular users manage their own. See App Management for the full flow.

Pre-release builds — the canary channel
Note

Listenarr’s upstream has not cut a stable release yet; every build it publishes is a canary pre-release. A default install prefers the stable channel, finds no stable release, and automatically falls forward to the newest canary build with a notice. The channel you installed with is recorded, and once upstream publishes its first stable release, a later update picks it up automatically. See Channels & Versions for how channels work.

Automatic port assignment
Tip

The upstream default port is 4545, but QuickBox assigns each user their own free port at install time and binds it to 127.0.0.1 only — nginx is the sole public entry point. The assigned port is recorded in the QuickBox database and shown on the Listenarr row in your Application Control panel. You never need to touch it.

Install and manage from the CLI

The CLI runs the same install and is suited to automation and scripting. The --beta flag selects the canary channel explicitly (the same pre-release builds the Dashboard falls forward to):

bash
qb install listenarr -u username
qb install listenarr -u username --beta
qb reinstall listenarr -u username
qb update listenarr -u username
qb update listenarr -u username --beta
qb remove listenarr -u username
qb help listenarr

The complete command set:

CommandDescription
qb install listenarr -u username
Install Listenarr for the user at the per-user subpath
qb install listenarr -u username --beta
Install and explicitly track the canary (pre-release) channel
qb reinstall listenarr -u username
Remove and reinstall Listenarr. This deletes its data, so back up first
qb update listenarr -u username
Update to the newest release on your recorded channel — your data is untouched
qb update listenarr -u username --beta
Update to the newest canary build for this update run
qb remove listenarr -u username
Remove Listenarr and clean up its files
qb help listenarr
Display comprehensive help information

Updates honor the channel you installed with, so you only pass --beta to track canary explicitly. Full flag reference: CLI Reference.


Access and authentication

URL

Listenarr is published under the per-user subpath of your QuickBox server:

https://your-server/username/listenarr/

The bundled web client is patched for this exact path at install time, so the subpath is served natively — including the WebSocket connections that power live download progress and log streaming. You can also click Open on the Listenarr row in the dashboard’s App Dashboard to launch the UI directly.

Enable authentication first

Listenarr ships with authentication DISABLED
Warning

Out of the box, Listenarr does not ask for a login — its built-in authentication is off by default, and QuickBox does not place a password gate in front of it. Until you enable authentication, anyone who can reach your server’s URL can open your Listenarr UI and its API. Make enabling Listenarr’s built-in authentication your first step after install.

To lock your instance down:

  1. Open https://your-server/username/listenarr/
  2. Go to Listenarr’s Settings and enable authentication
  3. Set a username and a strong password, then save — the UI switches to a login page from that point on

QuickBox does not generate, write, or store any Listenarr credentials — there is no default password, no credentials file, and nothing to reveal in the dashboard. The account exists only after you create it inside the app.

API key

Listenarr generates its API key on first start. The easiest place to get it is the dashboard: open the App Dashboard, stay on Application Control and expand Listenarr’s row. The API & Secrets section shows the key masked, with buttons to reveal it and copy it. Use it when a download client, script, or companion tool asks for it.

From a shell, the key is the top-level ApiKey value in config.json:

bash
jq -r .ApiKey /home/username/.config/Listenarr/config/config.json

Configuration and files

Listenarr keeps the application install and your data in two separate trees. Everything that matters to you — the database, settings, and logs — lives under /home/username/.config/Listenarr/. The install tree under /opt/username/Listenarr/ carries zero state and is fully replaced on every update.

Path
Description
/
opt/
username/
Listenarr/
Install tree — the extracted release, fully replaceable
Listenarr.Api
Self-contained single-file server executable run by the systemd unit
wwwroot/
Pre-built web client, patched at install for your per-user URL path
home/
username/.config/Listenarr/
Per-user state tree — all your data lives here
.channel
Release-channel marker (stable or canary) honored by qb update
wwwroot
Symlink to the patched web client in the install tree (refreshed on update)
config/
Application config root — also holds data-protection keys and the image cache
config.json
Port, URL path, bind address, API key and the authentication setting
appsettings/appsettings.json
Text configuration file (most runtime settings live in the database instead)
database/listenarr.db
The Listenarr SQLite database — library and settings
logs/
Date-rolled application log files (listenarr-YYYYMMDD.log)
etc/
nginx/software/
username.listenarr.conf
Subpath reverse proxy with WebSocket support for live updates
systemd/system/
listenarr@username.service
Per-user systemd unit — your assigned port and state path are baked in

Nearly all of Listenarr’s settings live in its SQLite database and are managed through the web UI — appsettings.json exists, but you will rarely need to touch it. The listen port and the state-tree location are managed by QuickBox through the systemd unit and kept in sync with nginx and the QuickBox database automatically.


Service management

Listenarr runs as a single per-user systemd unit:

bash
# Check status
sudo systemctl status listenarr@username
 
# Restart / stop / start
sudo systemctl restart listenarr@username
sudo systemctl stop listenarr@username
sudo systemctl start listenarr@username
 
# Follow the service log
sudo journalctl -u listenarr@username -f

The service starts automatically at boot. Listenarr’s database migrates itself during startup after an update — no manual migration step is ever needed; the web UI simply answers once the migration completes (typically a few seconds). The systemd journal carries the full service output and is the first place to look; Listenarr also writes date-rolled log files under /home/username/.config/Listenarr/config/logs/.


Common tasks

Enable authentication

Do this first — see Enable authentication first above. Open the app, go to Settings, enable authentication, and set a username and strong password.

Add a download client

  1. In the Listenarr UI, open the download client settings
  2. Add your client — qBittorrent, Transmission, SABnzbd, or NZBGet — with its host, port, and credentials
  3. On a QuickBox server your clients run on the same machine, so localhost plus the client’s assigned port is the usual shape
  4. Test the connection and save — Listenarr hands every grab to the client from then on

Update Listenarr

bash
qb update listenarr -u username

The update stops the service, replaces the install tree with the newest release on your recorded channel, re-patches the fresh web client for your URL path, and starts the service again. Your database, settings, and logs are untouched — all state lives outside the install tree. Add --beta to pull the newest canary build for that update run.

Check the logs

bash
# Service output (the canonical log stream)
sudo journalctl -u listenarr@username -f
 
# In-app date-rolled log files
ls /home/username/.config/Listenarr/config/logs/

Back up and restore

QuickBox backs Listenarr up for you from the dashboard or the CLI, with no need to stop the service and archive the folder by hand. Every backup is saved to /home/username/.QuickBox/software/listenarr/backup/, named with the version and the date.

BackupWhat it saves
Config Onlyappsettings.json, the small text configuration file. Your library and most settings are in the database, so use Full Backup for them
Full BackupTwo archives: listenarr-<version>-config_<date>.tar.gz holds your state tree under /home/username/.config/Listenarr/ (config.json, the config folder and a consistent copy of the listenarr.db database), and listenarr-<version>-application_<date>.tar.gz holds the install tree
NginxListenarr’s nginx config, username.listenarr.conf

From the dashboard: open Content → Asset Management Center (AMC in the sidebar), choose the Application Backups tab, expand the Listenarr row and click Back up now, then pick Full Backup, Config Only or Nginx. The same row lists every saved file with download and delete buttons. To restore, open the App Dashboard, stay on Application Control, expand the Listenarr row and click Restore in the Operations section. The window lists config, nginx and full backups; for a full backup its button reads Rollback and puts back both the install tree and the config archive. Restore appears only when your account is allowed to restore backups. See App Management → Application Backups for who can see the tab.

From the CLI:

bash
# Config Only: appsettings.json
qb manage software -o backup -u username -s listenarr
 
# Full Backup: state tree with the database, plus the install tree
qb manage software -o backup -o app -u username -s listenarr
 
# Roll back to a Full Backup: pick the version from a menu, then confirm
qb manage software -o rollback -o app -u username -s listenarr

Every option is described in the qb manage reference.

Remove and reinstall delete your backups
Caution

The backup folder belongs to the app: qb remove listenarr and qb reinstall listenarr both delete /home/username/.QuickBox/software/listenarr/ with every backup in it, and clear the rollback list. Before either one, download the Full Backup from the Application Backups tab, or copy the folder somewhere QuickBox does not manage:

bash
cp -a /home/username/.QuickBox/software/listenarr/backup /home/username/listenarr-backup-saved

Restore your library after a remove

A fresh install gets a new port and a new API key, so put back the database only and keep the new config.json, which matches the nginx config QuickBox just wrote. Run the file commands as your own account:

bash
qb install listenarr -u username
sudo systemctl stop listenarr@username
rm -f /home/username/.config/Listenarr/config/database/listenarr.db-wal /home/username/.config/Listenarr/config/database/listenarr.db-shm
tar -xzf /home/username/listenarr-backup-saved/listenarr-<version>-config_<date>.tar.gz -C /home/username/.config/Listenarr ./config/database/listenarr.db
sudo systemctl start listenarr@username

Removing the two -wal/-shm files first stops the new install’s journal from being applied to the restored database. Your library comes back as it was in the backup. Apps that call Listenarr need the new API key: copy it from API & Secrets on Listenarr’s row in the App Dashboard (see API key).

Remove Listenarr

bash
qb remove listenarr -u username
Remove and reinstall wipe ALL your data
Caution

Both qb remove listenarr and qb reinstall listenarr delete the full per-user state tree at /home/username/.config/Listenarr/ — the database, your library records, settings, API key, and logs — along with the install tree, the systemd unit, the nginx config, and the backup folder. Take a Full Backup and copy it out first (see Back up and restore) if there is any chance you will want your library back. Your actual audiobook and eBook files in your media folders are NOT touched.


Troubleshooting

Service will not start
Warning

Check the journal first: sudo journalctl -u listenarr@username -n 100. The most common causes are filesystem permission drift under the state tree (files under /home/username/.config/Listenarr/ must be owned by your user) and an interrupted update (rerun qb update listenarr -u username to redeploy a clean install tree).

Install fails with a patch error
Info

At install and update time, QuickBox patches the bundled web client so it serves correctly from your per-user URL path — and it verifies every patch location before rewriting anything. If upstream changes its frontend layout, the install fails loudly with a patch error instead of leaving you with a broken white-screen UI. If you hit this, an upstream build changed shape before QuickBox caught up: report it on the QuickBox Discord and retry after the next QuickBox update.

Install seems to pause at service start
Info

The install waits for Listenarr to actually answer HTTP before reporting success — the first start runs the database setup, which takes a few seconds. The wait is bounded at two minutes; if the service never answers, the install fails with a service error and the journal (sudo journalctl -u listenarr@username) tells you why.

Blank page or 404ing assets
Warning

The web client is patched for exactly one URL path. If an update was interrupted partway, the client and the URL can disagree — run qb update listenarr -u username to redeploy and re-patch a clean copy.


Best practices

Do

  • Enable Listenarr's built-in authentication immediately after install — the UI and API ship unprotected by default
  • Take a Full Backup regularly, from the Operations section of the expanded Listenarr row in the App Dashboard, from the Application Backups tab of the Asset Management Center, or with qb manage software -o backup -o app, since the database, settings, and API key all live in /home/username/.config/Listenarr/
  • Use qb update listenarr -u username for updates — it replaces the install tree and re-patches the web client while leaving your data untouched
  • Expect change between updates — Listenarr is a young community project shipping pre-release builds, and the UI evolves quickly

Don't

  • Don't run qb remove or qb reinstall before copying your backups out of .QuickBox — both permanently wipe your database and settings, and delete the backup folder too
  • Don't edit the port in the systemd unit by hand — nginx and the QuickBox database must agree with it, and QuickBox manages all three together
  • Don't delete the .channel marker in the state tree — qb update uses it to keep you on the channel you installed with
  • Don't install Listenarr from Docker or upstream packages alongside the QuickBox package — they will fight over ports and data paths

FAQ

Resources

Join the Community

Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.

  • Dedicated Support
  • Feature Previews
  • Community Configs
  • Active Discussions
Join Discord Server
Last updated on