Audiobookshelf: your audiobooks and podcasts, hosted at home

Audiobookshelf turns a folder of audiobook files on your NAS into a proper listening service: a tidy library with covers, descriptions and chapters, a podcast catcher that downloads new episodes for you, apps for your phone, and — the feature that sells it — your place in every book, remembered on the server and synced to whichever device you pick up next.

Published Nov 17, 2026 · Last updated Nov 18, 2026

Commercial audiobook apps are excellent right up until a title leaves the catalogue, a subscription lapses, or you want your partner’s progress kept separate from yours. If your books exist as ordinary files — ripped from CDs you own, bought from DRM-free stores, or downloaded from your audiobook accounts in a portable format — Audiobookshelf gives them the polished app experience without handing the library to anyone. It is free, open source, and one of the easiest containers on this site to live with.

What Audiobookshelf does

At its heart it is a server plus a scanner. You point a library at a folder of audiobooks, and Audiobookshelf reads embedded file metadata and folder names to group files into books, detect series and chapter markers (including proper chapter support in m4b files), and lay everything out as a browsable shelf. Where metadata is thin, its Match tool pulls covers, descriptions, narrators and series information from online book databases, including Audible catalogue data. Playback streams to the official iOS and Android apps or the web player, with variable speed, a sleep timer and bookmarks — and all of it is tracked per user, on the server, so progress is a property of your account, not of one phone. Podcasts are a second library type: subscribe to a show by its RSS feed and Audiobookshelf checks the feed on a schedule and downloads new episodes automatically, ready in the same app as your books.

Diagram of audiobook files and podcast feeds flowing into Audiobookshelf on a NAS, then out to a phone app and web player
Files and podcast feeds come in one side; a polished library with synced progress comes out the other.

What you need

Step-by-step installation

  1. Create the folders. Media folders for audiobooks and podcasts, plus the config and metadata folders on your NAS’s Docker storage.
  2. Write the compose file from the example below and start it with docker compose up -d.
  3. Open the web interface at http://your-nas-address:3333 and create the first account. That first account is the root (administrator) account — give it a strong password and keep it for admin tasks.
  4. Create an Audiobooks library pointing at the /audiobooks folder inside the container, and let the first scan run. Most well-tagged books appear immediately, covers and all.
  5. Fix the mismatches with Match. Open any book that scanned poorly, choose Match, search the metadata providers, and apply the result — cover, description, narrator and series order usually fall into place in one step.
  6. Tidy the stubborn ones at the source. If a book refuses to identify itself, fix its folder names to the Author / Title structure described below and rescan, rather than fighting the matcher book by book.
  7. Create a normal account for each listener in the household. Progress, bookmarks and shelves are per user; sharing one login means sharing one “where was I” across the whole family.
  8. Install the mobile app, sign in with your server address and your own account, and download a book for offline listening.
  9. Test the sync. Start a book in the web player, listen for a minute, pause, then open the app on your phone. You will be offered your exact place. That moment is the entire point of the project.
  10. Add a Podcasts library pointing at /podcasts, add a show by pasting its RSS feed URL, enable automatic downloads, and set a sensible limit on how many episodes to keep per show.
  11. Back up /config and /metadata on your normal NAS backup schedule. The audio files can be re-ripped or re-downloaded; your family’s listening progress cannot. One decision to make consciously: downloaded podcast episodes live in the /podcasts folder, which a /config-and-/metadata backup does not cover. Include the podcast downloads folder in the backup if those episodes must be preserved — otherwise, accept that after a restore they would need to be downloaded again. Either way, listening progress and user data remain the backup priority.

A concrete configuration example

services:
  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    container_name: audiobookshelf
    environment:
      - TZ=Etc/UTC
    volumes:
      - /volume1/audiobooks:/audiobooks
      - /volume1/podcasts:/podcasts
      - /volume1/docker/audiobookshelf/config:/config
      - /volume1/docker/audiobookshelf/metadata:/metadata
    ports:
      - "3333:3333"
    restart: unless-stopped

Four mounts, four jobs: the two media folders hold the actual audio, while /config and /metadata hold everything Audiobookshelf knows — accounts, libraries, progress, covers. Keep those two on the NAS’s local Docker storage rather than a network share, and note that the podcasts folder must stay writable, because that is where new episodes land. The web interface and apps all talk to port 3333.

Diagram showing listening progress stored on the Audiobookshelf server, so a phone and a tablet resume the same book at the same place
Progress lives on the server, per user — pause on one device, resume on another, at the exact same second.

Getting the library structure right

The scanner is good, but it is not psychic, and the single biggest factor in a clean library is folder structure. The layout that scans perfectly is Audiobooks / Author Name / Book Title /, containing either one audio file (a single m4b is ideal) or the numbered parts of a multi-file book. Series fit naturally as Author Name / Series Name / Book Title /. Three rules cover almost every scanning problem. First, one book per folder: a folder containing three books becomes one confused item, and hundreds of loose files in the library root become an afternoon of manual fixing. Second, embedded metadata wins: a well-tagged m4b — title, author, narrator, year, cover art — scans correctly almost regardless of folders, while untagged MP3 rips lean entirely on folder names, so keep those names clean and consistent. Third, use Match for polish, not rescue: with the structure right, matching is a two-click enrichment; with it wrong, fix the folders and rescan instead. Podcasts need none of this — Audiobookshelf manages downloaded episodes inside the podcast library folder itself.

Listening on your phone, away from home

The official apps for iOS and Android stream over your network at home and download books for offline listening away from it — flights, commutes, dog walks. Chapters, bookmarks, the sleep timer and playback speed are all there, and because progress is stored on the server against your account, the web player at your desk, the phone in the car and a tablet at night all agree on where you are in a book. For access away from home, do not port-forward port 3333 to the internet. Reach the server the safe way — a VPN-style connection such as Tailscale, or an HTTPS reverse proxy — and simply give the app that address instead of the home one.

Common mistakes and troubleshooting

Books show up merged, split or coverless

Almost always folder structure or missing tags. One book per Author / Title folder, then rescan, then Match for the cover and description. A “book” that contains three novels’ files will never sort itself out on its own.

Everyone’s listening progress keeps colliding

The household is sharing one account. Progress is deliberately per user — create an account for each listener and keep the root account for administration only.

The podcast folder quietly ate the disk

Automatic downloads with no retention limit will do that over a year of daily shows. Set a maximum number of episodes to keep for each podcast, and glance at the podcast folder’s size when you do your other NAS housekeeping.

The app cannot reach the server away from home

You gave it the home LAN address, which does not exist on mobile data. Connect through your VPN or use your reverse-proxy address in the app’s server setting — and test it on mobile data before a trip, not during one.

An update made the library look empty

Do not rescan from scratch and do not panic. The library lives in the /config and /metadata mounts, not in the container. Check your compose file still points those mounts at the same folders, and the library will reappear exactly as it was.

Official documentation and references

Frequently asked questions

Can I listen to my Audible books with it?

Only once they are ordinary, DRM-free files. Audible purchases are locked to Audible’s own apps, so many listeners use a tool such as Libation to download and convert books they own into standard m4b or MP3 files first. From that point on, Audiobookshelf treats them like any other audiobook — which is rather the point of owning them.

Which app should I listen with?

The official Audiobookshelf app for iOS or Android, or the web player in any browser. Because your place in each book is stored on the server, you can start in one and continue in another without hunting for your spot.

How much space do podcasts take?

It depends on the shows and your retention settings. A handful of weekly shows capped at ten episodes each is a few gigabytes; an uncapped daily news podcast is a slow leak. Set the per-show episode limit when you subscribe and it stops being a question.