Audiobookshelf: a self-hosted audiobook and podcast server

The problem Audiobookshelf solves for people with their own audio files

Most audiobook apps assume you buy from one store and stay inside it. Podcast apps assume feeds and nothing else. If your library is a folder of m4b files, a pile of mp3 chapters, and a handful of podcast feeds you want archived locally, you end up with two apps and no shared progress. Audiobookshelf puts both in one server: the README describes it as a self-hosted audiobook and podcast server that streams all audio formats on the fly, keeps progress per user, and syncs that progress across devices. It is aimed at the person who already has the files. The README says nothing about acquiring audio, and there is no store integration to look for. The library is whatever you mount. That is the whole premise, and it decides who the project is for: someone with storage, a machine that stays on, and a reason to keep the library off a vendor's servers.

How the server, the client and the mobile apps fit together

The repository is a Node.js server with a compiled frontend. package.json lists express, express-session, express-rate-limit and sqlite3 among the dependencies, and the Dockerfile builds the client in one stage, the server in another, then copies both into a node:20-alpine runtime image. The entrypoint is index.js and the container exposes port 80 by default, with ENV PORT=80 set in the image. The docker-compose example maps 13378 on the host to 80 inside the container, which is where the widely used 13378 port comes from. Media is not bundled: the compose file mounts ./audiobooks and ./podcasts as library roots, ./metadata for generated metadata, and ./config for configuration, and the comment in that file warns that the config directory needs to be on the same physical machine you are running the server on. Progress sync depends on a websocket connection. The README states this plainly under reverse proxy setup, and adds that subfolder hosting is supported but the path must be /audiobookshelf and is not changeable. The mobile clients are separate: the Android app is on Google Play and the iOS app is distributed through Test Flight, with the README noting the iOS beta is full because Apple caps beta testers at 10k. That is a real constraint on iOS access today, not a documentation gap.

Installing Audiobookshelf with Docker and adding a first library

The README points installation at the install docs and ships a docker-compose.yml in the repository root as an example. The compose file uses the image ghcr.io/advplyr/audiobookshelf:latest and maps host port 13378 to container port 80. The comment in the file is explicit that if you change the port you should change only the external side, not the internal one.

services:
  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    ports:
      - 13378:80
    volumes:
      - ./audiobooks:/audiobooks
      - ./podcasts:/podcasts
      - ./metadata:/metadata
      - ./config:/config
    restart: unless-stopped

Bring it up with docker compose up -d from the directory holding that file, then open http://localhost:13378 in a browser. The first screen creates the root user account. After that, a library is created in the web UI and pointed at one of the mounted paths, in this example /audiobooks. The README is emphatic that directory structure and folder names matter to Audiobookshelf and links the library docs for supported layouts, folder naming conventions and how audio file metadata is used. So the order that works is: arrange the files first, then create the library. If you would rather not use Docker, the README says the application is built using NodeJs and documents a manual setup with NodeJs version 20 and FFmpeg, a dev.js file in the project root based on .devcontainer/dev.js, and a client build via npm ci, cd client, npm ci, npm run generate. The server then starts with npm run dev, with the client on localhost:3333 by default, a port configurable in dev.js. That path is development-oriented; the Docker route is the one the repository presents as the example deployment.

Where Audiobookshelf gets in your way

The websocket requirement is the sharpest edge. Any reverse proxy in front of the server has to pass websocket connections, and if it does not, progress sync degrades in ways that are not obvious from the UI. Subfolder hosting works only under the fixed path /audiobookshelf, so a proxy layout built around a different prefix has to change. The config volume is another constraint the compose file states outright: it must live on the same physical machine as the server. Anyone planning to keep config on a network share should read that comment twice. On the client side, the iOS beta is full, so iPhone access today means the PWA or a third-party client rather than the official app. The README also carries a notice that frontend pull requests are not being reviewed or merged for the existing Vue frontend because it is being rewritten in React. For a user this changes little in the short term. For anyone planning to contribute UI work, it means the code you would patch is on its way out. Finally, this is a server you operate. Daily backups of metadata are automated per the feature list, but the audio files themselves are your responsibility, and nothing in the repository does that for you.

Audiobookshelf compared with Plex and Jellyfin for audio

Plex and Jellyfin are the obvious alternatives, and the difference is in what the data model is built around. Both started with video and treat music and audiobooks as secondary library types. Audiobookshelf starts from the audiobook: chapter editing, chapter lookup through the Audnexus API, merging audio files into a single m4b, embedding metadata and cover art back into the files, and open RSS feeds for podcasts and audiobooks. Those are first-class features in the README, not plugins. The trade-off runs the other way too. Plex and Jellyfin have mature video clients on nearly every platform and large plugin ecosystems; Audiobookshelf has neither, and its own clients are the web PWA plus beta mobile apps. If your library is mostly film and television with a few audiobooks on the side, a general media server is the more sensible host. If the audiobook and podcast collection is the point, and you want chapter tooling and progress sync rather than a video-first interface, Audiobookshelf is the more direct fit.

Licence, maintenance and what an upgrade actually costs

The licence is GPL-3.0, stated in package.json and the LICENSE file. For self-hosting that is unremarkable: you can run it, modify it and redistribute under the same terms. It matters if you intend to build a closed product on top of the server code, because the copyleft applies to derivative distributions. This is a description of the licence, not legal advice; read the licence text for your own case. On maintenance, the repository is not archived and the last push was on 2026-07-27, which is the v2.36.0 release date. The two releases before it are v2.35.1 on 2026-05-28 and v2.35.0 on 2026-05-17, so the cadence in that window is roughly monthly to six-weekly. Upgrades via Docker are a pull and a restart; the container runs database migrations from server/migrations at startup, which the pkg assets list in package.json confirms are shipped with the server. The cost that is easy to underestimate is not the upgrade, it is the layout: because folder names and directory structure drive what the scanner sees, reorganising a library later means re-checking matches and metadata rather than moving files and walking away.

Editorial conclusion

Adopt Audiobookshelf if you already own the audio files, can keep a machine running, and want per-user progress synced across the web app and the mobile apps. Do not adopt it if you want a hosted catalogue you do not have to store or back up, or if you cannot run a websocket-capable reverse proxy for remote access. Before committing, verify three things: that your folder layout matches the library docs, that your reverse proxy passes websocket connections, and that the metadata and config directories are on persistent storage, since the docker-compose example mounts ./metadata and ./config as separate volumes.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes