Skip to Content
AudioBookShelf

AudioBookShelf

Self-hosted audiobook and podcast server

Overview

AudioBookShelf is a self-hosted audiobook and podcast server. It organizes your audiobooks and podcasts into libraries, keeps your listening position in sync across the web client and the official iOS and Android apps, subscribes to podcast RSS feeds with automatic episode downloads, and matches rich metadata (covers, narrators, series, chapters) from Audible, iTunes, and Google Books. AudioBookShelf ships its own complete multi-user authentication — you create the admin account in your browser on first visit, and manage additional users with per-library permissions inside the app.

QuickBox Pro installs AudioBookShelf per user, built from source: the installer clones the latest upstream release tag, provisions an isolated Node.js runtime maintained to the QuickBox security minimum for your user, compiles the native SQLite bindings, and generates the web client with your personal URL path baked in. The result is a single systemd service served at https://your-server/username/audiobookshelf/ through a clean nginx reverse proxy — no rewrites, no path tricks. Docker images and the upstream .deb package are upstream alternatives and are not used by the QuickBox package.

Because the install is a real source build, the first install (and every update) takes noticeably longer than a binary application — expect several minutes while dependencies compile and the web client is generated.


Key features

Audiobook & Podcast Library

Organize audiobooks and podcasts with chapters, series, collections, and per-book progress tracking

Progress Sync

Listening position stays in sync across the web client and the official iOS and Android apps in real time

Podcast Auto-Download

Subscribe to RSS feeds with scheduled episode downloads, retention rules, and episode search

Metadata Matching

Covers, descriptions, narrators, series, and chapters from Audible, iTunes, and Google Books

Built-In Multi-User Auth

Per-user accounts with granular library permissions; the admin account is created in-browser on first visit

Mobile Apps

Official iOS and Android apps with offline listening and background playback

Per-User Service

Security-maintained, isolated Node.js runtime and systemd unit audiobookshelf@username with auto-allocated port and loopback-only binding

Reverse-Proxy Ready

Native nginx subpath at /username/audiobookshelf/ with WebSocket support and optional custom-domain SSL

When to use it

Good fit

  • You want a self-hosted home for your audiobook collection with chapter support and progress tracking
  • You want podcast subscriptions that download new episodes automatically
  • Multiple people share your audiobook library and need their own accounts and listening positions
  • You listen on the go and want official mobile apps with offline playback

What you get

  • Install via qb install audiobookshelf -u username — built from source with an isolated Node.js runtime maintained to the QuickBox security minimum
  • Served at https://your-server/username/audiobookshelf/ by default, with optional custom subdomain and SSL
  • Single per-user systemd service audiobookshelf@username with auto-start on boot
  • For a full music server, look at Airsonic or Subsonic instead; for comics and manga, look at Kavita or Komga

Installation

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find AudioBookShelf under the Media Servers category, and click Install. The dashboard streams the install log live and AudioBookShelf 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 AudioBookShelf row in the App Dashboard.

In the install dialog you can switch the Custom Domain toggle to Custom and enter a domain — the install issues an SSL certificate and publishes AudioBookShelf on that subdomain (see Custom subdomain with SSL). Choose HTTP-01 (the default) or DNS-01 as the challenge method; DNS-01 also asks for the DNS provider.

The dashboard installs AudioBookShelf for the currently signed-in user; to install it for a different user, an admin uses the CLI with an explicit -u <other_user>. For the full package flow see App Management.

Install and manage from the CLI

The CLI runs the same install pipeline and is suited to automation and scripting. The -d domain (and optional --dns/--dns-provider) map to the Dashboard custom-domain fields above:

bash
qb install audiobookshelf -u username
qb install audiobookshelf -u username -d audiobookshelf.example.com
qb update audiobookshelf -u username
qb reinstall audiobookshelf -u username
qb remove audiobookshelf -u username
qb help audiobookshelf

Reinstall removes application state, including library accounts and progress. Back up and restore before reinstall or remove.

AudioBookShelf tracks stable tagged releases only — there is no --beta flag. Full flag reference: CLI Reference.

Source builds take a few minutes
Note

AudioBookShelf publishes no prebuilt Linux binaries, so QuickBox builds it from source. The first install and every update spend several minutes on dependency installation and the web client build — this is normal. You can follow the build in /opt/quickbox/logs/audiobookshelf.log.

Automatic port assignment
Tip

The upstream default port is 3333, 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 AudioBookShelf row in the dashboard’s App Dashboard. You never need to touch it.


Access and authentication

URL

AudioBookShelf is published under the per-user subpath of your QuickBox server by default:

https://your-server/username/audiobookshelf/

The web client is generated with this exact path baked in, so the subpath is served natively — including the socket.io WebSocket connection that powers real-time progress updates. You can also click Open on the AudioBookShelf row in the dashboard’s App Dashboard to launch the UI directly. When AudioBookShelf is published on a custom subdomain (see Custom subdomain with SSL below), the Open link points at https://<your-subdomain>/ instead.

First-run setup

AudioBookShelf manages its own accounts. On your first visit, the app shows an initialization screen where you create the admin (root) account in the browser — pick a username and a strong password. QuickBox does not generate, write, or store any AudioBookShelf credentials; there is no default password and no credentials file to retrieve.

  1. Open https://your-server/username/audiobookshelf/
  2. On the initialization screen, create the root user — choose a username and a strong password
  3. Sign in with the account you just created
  4. Create your first library: pick Books or Podcasts, then add one or more folders that hold your media
  5. AudioBookShelf scans the folders and matches metadata automatically

Additional accounts, per-library permissions, and all other user management live inside the app under Settings → Users. These AudioBookShelf accounts are separate from QuickBox accounts — every QuickBox user who installs AudioBookShelf gets their own private instance with its own users.

No QuickBox-generated credentials
Info

Unlike some QuickBox applications, there is no auto-generated admin password for AudioBookShelf and nothing to reveal in the dashboard. The root account exists only after you create it in the browser, and AudioBookShelf stores it in its own database.


Custom subdomain with SSL

By default AudioBookShelf serves under the per-user subpath of your main server address. You can also publish it on a dedicated subdomain (for example audiobookshelf.example.com) with a Let’s Encrypt certificate. There are three ways to set this up: a single-call install (Path A), a post-install retrofit from the CLI (Path B), and the dashboard SSL Control page (Path C).

Switching the URL rebuilds the web client
Note

AudioBookShelf bakes its serving path into the web client at build time. Whenever the install flips between the per-user subpath and a custom subdomain — in either direction — QuickBox automatically rebuilds the client for the new base. The service stops during the rebuild and starts again when it finishes; expect a few minutes of downtime for the flip. Your library, users, and progress are not affected.

Path A — Subdomain at install time

The fastest path is to pass -d <domain> to the install. The certificate is issued, the subdomain vhost is written, and the web client is built for the subdomain on the first try — you never see the subpath URL.

Point a DNS record (A or CNAME) for your chosen subdomain at the server, then run:

bash
qb install audiobookshelf -u username -d audiobookshelf.example.com

The install chain-calls Let’s Encrypt under the hood and auto-detects any saved DNS provider credentials, switching to the DNS-01 challenge automatically when it finds them. To force the DNS-01 challenge explicitly:

bash
qb install audiobookshelf -u username -d audiobookshelf.example.com --dns --dns-provider cloudflare

Path B — Retrofit a subdomain to an existing install

If AudioBookShelf is already running on the per-user subpath and you want to move it to a dedicated subdomain, issue the certificate with the AudioBookShelf-specific lecert flag:

bash
qb install lecert --audiobookshelf -d audiobookshelf.example.com -u username

This uses the same shape as every other lecert-managed application (--emby, --jellyfin, --plex, --komga, etc.). QuickBox:

  1. Requests a Let’s Encrypt certificate for the supplied domain (HTTP-01 challenge by default)
  2. Writes the subdomain vhost into /etc/nginx/sites-enabled/username.audiobookshelf.conf with your assigned port filled in
  3. Stops the service, rebuilds the web client for the subdomain root, and starts it again
  4. Reloads nginx and registers the certificate for automatic renewal

Wildcard or DNS challenge: add --dns --dns-provider cloudflare (or another supported provider). See the Let’s Encrypt application reference for the full list of supported DNS providers.

Testing without rate-limit exposure: add --staging to issue against the Let’s Encrypt staging CA, or --dry-run to validate the ACME challenge without writing any certificate or nginx changes. Combine the two to fully exercise the flow with zero side effects.

Removing the subdomain: qb remove lecert --audiobookshelf -d <domain> -u username deletes the subdomain vhost. If AudioBookShelf is still installed, QuickBox rebuilds the web client for the per-user subpath and restores the subpath nginx config, so subpath access continues to work.

Path C — Dashboard SSL Control

The dashboard’s SSL Control page at System → SSL Control (/system/ssl) exposes the same flow. The form fields, in order, are:

  1. Target — pick AudioBookShelf from the dropdown
  2. Domain — your chosen subdomain (for example audiobookshelf.example.com)
  3. Challenge Method — HTTP-01 (the default) or DNS-01
  4. DNS Provider — only shown when DNS-01 is selected
  5. DNS credentials — only shown when DNS-01 is selected and no credentials are saved for that provider yet
  6. Username — the QuickBox user that owns the install

The SSL Control page runs the same qb install lecert --audiobookshelf pipeline under the hood.

See the SSL Control page
Note

For end-to-end SSL setup, supported DNS providers, wildcard certificates, and renewal behavior, see the SSL Certificates dashboard page and the Let’s Encrypt application reference.


Configuration and files

AudioBookShelf keeps the application install and your library state in two separate trees. Everything that matters to you — the database, covers, cached metadata, and logs — lives under /home/username/.config/audiobookshelf/. The install tree under /opt/username/audiobookshelf/ is disposable and is rebuilt on every update.

Path
Description
/
opt/
username/
audiobookshelf/
Install tree — cloned source at the pinned release tag
client/dist/
Generated web client with the serving path baked in
env.conf
Runtime environment: PORT, HOST, CONFIG_PATH, METADATA_PATH, ROUTER_BASE_PATH (and FFMPEG_PATH when the system ffmpeg qualifies)
index.js
Server entry point run by the systemd unit
lib/
nodejs/Audiobookshelf/
Per-user, security-maintained Node.js runtime (runs the service and builds the client)
python/Audiobookshelf/
Per-user Python venv that bootstraps the Node runtime
quickbox/logs/
audiobookshelf.log
QuickBox install, update, and build log
home/
username/.config/audiobookshelf/
Per-user state tree — all your data lives here
.base_path
Marker recording the active serving base (subpath or subdomain) so updates rebuild correctly
config/
Application config dir (CONFIG_PATH)
absdatabase.sqlite
The AudioBookShelf database — users, libraries, progress, settings
logs/
Daily date-named application log files
metadata/
Cover art, cached metadata, and upload scratch space (METADATA_PATH)
etc/
nginx/software/
username.audiobookshelf.conf
Subpath reverse proxy (subdomain installs use sites-enabled instead)
systemd/system/
audiobookshelf@username.service
Per-user systemd unit

AudioBookShelf has no text settings file — all in-app settings live in the SQLite database and are managed through the web UI. The only file QuickBox manages is env.conf, which carries the runtime environment the systemd unit loads (port, bind address, data paths, and serving base). It is kept in sync automatically by installs, updates, and SSL flips.

Large uploads are already handled
Warning

The managed nginx config allows uploads up to 10 GB per file for audiobook and podcast uploads through the web UI, and holds WebSocket connections open for real-time progress sync. You do not need to tune nginx yourself.


Service management

AudioBookShelf runs as a single per-user systemd unit:

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

The service starts automatically at boot. The application’s SQLite database migrates itself on start after an update — no manual migration step is ever needed. In-app daily logs are also written to /home/username/.config/audiobookshelf/config/logs/, but the systemd journal carries the full output and is the first place to look.


Common tasks

Add an audiobook library

  1. Sign in and click the library switcher in the top bar, then Add Library (or go to Settings → Libraries)
  2. Choose Books as the media type and add the folder(s) that hold your audiobooks
  3. Save — AudioBookShelf scans the folders and matches covers, series, narrators, and chapters automatically

Subscribe to a podcast with auto-download

  1. Create a library with the Podcasts media type pointed at a folder for episode storage
  2. In the podcast library, click Add → Podcast and search by name or paste an RSS feed URL
  3. On the podcast’s page, enable Auto Download Episodes and set the check interval and retention to taste

Update AudioBookShelf

bash
qb update audiobookshelf -u username

The update backs up your database, fetches the newest stable release tag, rebuilds the server dependencies and the web client with the same serving base the install is using, and restarts the service. Your library, users, and progress are untouched — all state lives outside the install tree. Like the install, the update is a source build and takes a few minutes.

Check the logs

bash
# Service output (the canonical log stream)
sudo journalctl -u audiobookshelf@username -f
 
# In-app daily logs
ls /home/username/.config/audiobookshelf/config/logs/
 
# QuickBox install/update build log
tail -f /opt/quickbox/logs/audiobookshelf.log

Back up and restore

QuickBox backs the AudioBookShelf database 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/audiobookshelf/backup/.

BackupWhat it saves
Config Onlyabsdatabase.sqlite, the database that holds your user accounts, listening progress and library settings, as absdatabase.sqlite_<date> plus a copy named absdatabase.sqlite that is always the latest
Full BackupTwo archives: audiobookshelf-<version>-config_<date>.tar.gz holds the data folder /home/username/.config/audiobookshelf/ with a consistent copy of absdatabase.sqlite (logs are left out), and audiobookshelf-<version>-application_<date>.tar.gz holds the install tree
NginxAudioBookShelf’s nginx config, username.audiobookshelf.conf

Config Only does not include the covers and cached metadata under /home/username/.config/audiobookshelf/metadata/; Full Backup does. Your audiobook and podcast media files are never part of a backup.

From the dashboard: open Content → Asset Management Center (AMC in the sidebar), choose the Application Backups tab, expand the AudioBookShelf 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 AudioBookShelf row and click Restore in the Operations section, then pick the backup; for a full backup the button reads Rollback and puts back both archives. 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: absdatabase.sqlite
qb manage software -o backup -u username -s audiobookshelf
 
# Full Backup: the data folder and the install tree
qb manage software -o backup -o app -u username -s audiobookshelf
 
# Put back the most recent database backup
qb manage software -o restore -u username -s audiobookshelf
 
# Roll back to a Full Backup: pick the version from a menu, then confirm
qb manage software -o rollback -o app -u username -s audiobookshelf

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 audiobookshelf and qb reinstall audiobookshelf both delete /home/username/.QuickBox/software/audiobookshelf/ with every backup in it. 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/audiobookshelf/backup /home/username/audiobookshelf-backup-saved

Restore your accounts and progress after a remove

Put the saved database back into the fresh install with the service stopped. Run the file commands as your own account:

bash
qb install audiobookshelf -u username
sudo systemctl stop audiobookshelf@username
rm -f /home/username/.config/audiobookshelf/config/absdatabase.sqlite-wal /home/username/.config/audiobookshelf/config/absdatabase.sqlite-shm
cp /home/username/audiobookshelf-backup-saved/absdatabase.sqlite /home/username/.config/audiobookshelf/config/absdatabase.sqlite
sudo systemctl start audiobookshelf@username

Removing the -wal/-shm files first stops the new install’s journal from being applied to the restored database. Your accounts and listening progress come back as they were in the backup; covers and cached metadata are not in a Config Only backup.

Remove AudioBookShelf

bash
qb remove audiobookshelf -u username
Remove and reinstall wipe application state
Caution

Both qb remove audiobookshelf and qb reinstall audiobookshelf delete the full per-user state tree at /home/username/.config/audiobookshelf/ — the database, every user account, listening progress, covers, cached metadata, and logs — along with the install tree and the per-user Node runtime. Download a backup and copy it out first (see Back up and restore) if there is any chance you will want your accounts and progress back. The backup folder at /home/username/.QuickBox/software/audiobookshelf/ is deleted too. Your actual audiobook and podcast media files in your library folders are NOT touched.


Node.js security minimum

AudioBookShelf now uses the QuickBox security minimum on Node.js 22 rather than the older Node.js 20 runtime. The same isolated runtime builds the client and starts the service. The current QuickBox policy sets 22.23.4 as the minimum for Node.js 22. This is a security minimum, not a permanent version pin; later QuickBox updates can raise it.

QuickBox checks existing app copies during qb update quickbox and attempts to raise copies below the security minimum. An app update also applies the policy. Check the app-specific copy as the affected account:

bash
sudo -u username /opt/username/lib/nodejs/Audiobookshelf/.venv/bin/node --version

The shell’s node --version may report a different system or user-managed installation. It does not identify the copy QuickBox provisions for AudioBookShelf. Do not downgrade Node.js to match an older example or replace the system Node.js package as a workaround.

Troubleshooting

”The Node.js security floor list cannot be read”

If an install or update reports The Node.js security floor list (/opt/quickbox/config/software/node-security-floor) cannot be read, QuickBox could not validate its security policy. The file can exist and still fail validation: unreadable contents, a malformed entry, or a missing min= entry all cause this error. The application step stops rather than choosing an unverified Node.js version.

Run these read-only checks as the server administrator:

bash
ls -l /opt/quickbox/config/software/node-security-floor
sed -n 'l' /opt/quickbox/config/software/node-security-floor

The list contains a min=x.y.z entry and release-line entries such as 22=22.23.4; each numbered key must match the major in its version. Comments and blank lines are allowed. The sed output also exposes unexpected characters and line endings, so send its exact output rather than only a directory listing.

If QuickBox has not finished updating, complete qb update quickbox first and retain any update errors. If that succeeds but this error persists, send support the two checks above, the exact failing command, OS and QuickBox versions, and the relevant package-log excerpt. Retry qb update audiobookshelf -u username only after the policy issue has been resolved; use the install command instead for an installation that never completed.

Do not bypass the security check
Warning

Do not create or edit the policy file manually or bypass the check.

Node.js security update could not finish

If the QuickBox update says the app still runs a version below the security floor, the attempted move failed and the old runtime may still be in use. Resolve the logged failure, then retry qb update audiobookshelf -u username. Keep any further error output for support.

If the update specifically says audiobookshelf@username.service could not restart after replacing Node.js, inspect its journal, then run systemctl restart audiobookshelf@username. Confirm the app opens from the App Dashboard after the restart. The version command above checks the copy on disk, so it alone does not prove a previously running process switched to the new binary.

Restore-failed warning
Warning

A restore-failed warning means the app may not start. Do not delete recovery directories or use reinstall as the first repair.

Install or update seems stuck

Dependency installation and client generation can take several minutes. Read the build log before cancelling the operation:

bash
tail -n 200 /opt/quickbox/logs/audiobookshelf.log
df -h /opt /home
df -i /opt /home
free -h

If the operation exits with a resource or build error, address that error before retrying. Do not run a second package operation while the first is still building.

Service will not start or the health check times out

Replace username with the affected account and run these read-only checks as the server administrator:

bash
systemctl status audiobookshelf@username --no-pager
journalctl -u audiobookshelf@username -n 100 --no-pager
sudo -u username /opt/username/lib/nodejs/Audiobookshelf/.venv/bin/node --version
ls -l /opt/username/audiobookshelf/client/dist/index.html
ls -ld /home/username/.config/audiobookshelf/config

Check the Node.js security minimum for the expected runtime. A missing client artifact or SQLite module error points to an incomplete dependency/client build; a permission error under the state tree needs attention to that exact path. Back up your library state, resolve the logged cause, then retry qb update audiobookshelf -u username.

On first start, the app may fetch its SQLite extension and, when the system FFmpeg is too old, its own FFmpeg. A health-check failure can therefore require checking the journal for a download error as well as a service crash. An active service alone does not prove the page works; open AudioBookShelf from the App Dashboard and confirm your library loads.

Reinstall removes the state tree
Caution

Update rebuilds the runtime, server dependencies, and client without removing the separate state tree. Reinstall removes that state tree.

Blank page or missing assets after switching URLs

The client and server must use the same serving base. Check the selected base and generated client:

bash
cat /home/username/.config/audiobookshelf/.base_path
grep -E '^(HOST|PORT|ROUTER_BASE_PATH)=' /opt/username/audiobookshelf/env.conf
ls -l /opt/username/audiobookshelf/client/dist/index.html
nginx -t

A marker of / means subdomain mode; the default subpath is /username/audiobookshelf. If the switch was interrupted, run qb update audiobookshelf -u username to regenerate the client using the saved serving base. If the marker and active URL disagree, share the evidence with support before manually editing them.

Forgot the admin password

QuickBox does not manage AudioBookShelf’s app accounts. If another administrator can sign in, use that account to reset the password in Settings → Users.

Reinstall deletes accounts and progress
Caution

Copy a backup out of .QuickBox before attempting database recovery; reinstall deletes accounts, listening progress and the backup folder.

What to send support

Include the exact failing command, OS and QuickBox versions, runtime check above, journal, and the relevant excerpt of /opt/quickbox/logs/audiobookshelf.log. Redact account tokens, credentials, and private URLs. Do not attach the database or the entire state tree to a public discussion.


Best practices

Do

  • Choose a strong password for the root account you create on first run — the login page is reachable by anyone who can reach your server
  • Take a Config Only backup regularly, from the Application Backups tab in the Asset Management Center or with qb manage software -o backup, since the database holds your accounts and progress
  • Use qb update audiobookshelf -u username for updates — it backs up the database and rebuilds the client with the correct serving base
  • Use the official iOS and Android apps for on-the-go listening with progress sync
  • Keep an eye on free disk space — cover art and cached metadata under metadata/ grow with your library

Don't

  • Don't run qb remove audiobookshelf before copying your backups out of .QuickBox — it permanently wipes your database, users, progress, and the backup folder
  • Don't edit the port in env.conf by hand — nginx and the QuickBox database must agree with it, and QuickBox manages all three together
  • Don't delete the .base_path marker in the state tree — updates use it to rebuild the web client for the right URL
  • Don't install AudioBookShelf from apt or Docker 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