Set up Audiobookshelf with Docker Compose

Docker Compose is the easiest way to run Audiobookshelf, and the official docs recommend Docker. It works on Linux, macOS and Windows, and the same file handles updates.

What you need

• Docker with Compose: Docker Desktop on a Mac or Windows PC, or Docker Engine with the Compose plugin on Linux (install Docker Compose)
• A place for your audiobooks: a folder on your machine with your audiobook files

Quick start with Docker Compose

Create a docker-compose.yml file:

services:
  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    container_name: audiobookshelf
    ports:
      - 13378:80
    volumes:
      - ./audiobooks:/audiobooks
      - ./podcasts:/podcasts
      - ./config:/config
      - ./metadata:/metadata
    environment:
      - TZ=America/Toronto  # Change to your timezone
    restart: unless-stopped

Then run:

docker compose up -d

Open http://localhost:13378 in your browser and follow the first-time setup below. 13378 is the port on your computer. Inside the container, Audiobookshelf listens on 80. What port does Audiobookshelf use? explains the two numbers.

Or use Docker CLI directly

If you prefer a one-liner:

docker run -d \
  --name audiobookshelf \
  -p 13378:80 \
  -v /path/to/audiobooks:/audiobooks \
  -v /path/to/podcasts:/podcasts \
  -v /path/to/config:/config \
  -v /path/to/metadata:/metadata \
  -e TZ=America/Toronto \
  --restart unless-stopped \
  ghcr.io/advplyr/audiobookshelf:latest

Replace all four /path/to/... paths with real folders on your computer. If the folder doesn’t show up in Audiobookshelf later, see Audiobookshelf can’t see my audiobook folder.

What each volume does

Volume	What it stores	Important notes
/audiobooks	Your audiobook files	Can be on network storage (NFS/SMB)
/podcasts	Your podcast files (podcasts on the server)	Can be on network storage
/config	Database and settings	Must be on local storage (not network-mounted)
/metadata	Cache, covers, backups, logs	Can be on network storage

Pro tip: Keep /config on local storage. It holds the database, and the official docs warn that a database on network storage gets slow and can end up corrupted.

You can mount more media folders if your audiobooks live in several places. Add more lines under volumes: in the compose file, or more -v lines to the command.

Anything that isn’t in one of these folders lives inside the container and is deleted when an update replaces it. Library empty after a Docker update covers what goes missing and how to get it back.

Organizing your audiobooks

Give every book its own folder. Audiobookshelf reads details from folder names. The recommended structure:

/audiobooks
  /Author Name
    /Series Name
      /Book Title
        cover.jpg
        chapter1.mp3
        chapter2.mp3

It also reads ID3 tags from your audio files, so if your metadata is good, the folder structure matters less.

Some handy folder naming tricks that get parsed automatically:

• Series sequence: Book 1 - Title or Vol. 3 - Title (also Volume 12. Title, 6. Title, 0.5 - Title)
• Publish year: 2024 - Title
• Narrator: Title {Narrator Name} (curly braces)
• Subtitle: Title - Subtitle (separated by a dash with spaces), only with Parse subtitles turned on in the server settings

Audiobookshelf folder structure has the full rules, and why books sometimes merge into one.

First-time setup

1. Open http://YOUR-IP:13378 in a browser
2. Create your admin account
3. Click Libraries in the sidebar, then Add your first library
4. Select “Books” or “Podcasts” as the media type
5. Browse for your folder. Use the container path (e.g., /audiobooks), not the path on your host machine (can’t see your folder?)
6. Save, then open the empty library and click Scan Library to read your files (new books added later are picked up automatically by the file watcher)

Updating

docker compose pull
docker compose down
docker compose up -d

These mounts keep your data, settings and progress when the container is replaced, as long as /config, /metadata and your media are all mapped. Back up before updating (Settings > Backups > Create Backup). If a new version won’t start, see Audiobookshelf won’t start after a Docker upgrade.

Running as a specific user

If you need the container to run as a non-root user (common on NAS devices):

services:
  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    user: "1000:1000"  # Your user's UID:GID
    # ... rest of config

Find your UID/GID with id -u and id -g. Create the config and metadata folders first and make that user their owner, or the container stops with EACCES errors. Running Audiobookshelf as a non-root user has the steps.

Common environment variables

Variable	Default	What it does
TZ	System	Timezone (e.g., America/Toronto, Europe/London)
PORT	80 (internal)	Internal listening port (you probably don’t need to change this)
ACCESS_TOKEN_EXPIRY	3600	Seconds a sign-in stays valid before an app quietly renews it (1 hour)
REFRESH_TOKEN_EXPIRY	2592000	Seconds an app can go unused before you have to sign in again (30 days). Each renewal starts the count again

Common Docker setup mistakes

• Don’t nest volumes. Keep /config, /metadata, and your media directories separate. Nesting them inside each other causes weird issues.
• Only change the external port. If you want a different port, change the left side of the port mapping (e.g., 8080:80). Never change the 80 on the right.
• Network storage and the file watcher. If your audiobooks are on NFS or SMB, the real-time file watcher may not pick up changes reliably. Set up a scheduled library scan as a fallback (Settings > Libraries, edit your library, Schedule tab).

Connect SoundLeaf and listen away from home

• Connect SoundLeaf to your server: get the iOS app set up. What to type as your server address shows the address to enter
• Listen away from home: pick between Tailscale, a reverse proxy and a Cloudflare Tunnel