Audiobookshelf: A Self-Hosted Server for Audiobooks, Podcasts, and Ebooks

What Audiobookshelf Solves and Who It Is For

Audiobookshelf addresses a recurring problem for people who own large collections of audiobooks and podcasts: how to stream them from your own hardware without relying on commercial cloud services. The README describes it as a self-hosted audiobook and podcast server. The target user is someone who already runs a home server or a NAS, who is comfortable with Docker or Node.js, and who wants fine-grained control over their media library. It is not aimed at casual listeners who prefer a managed service; it requires ongoing maintenance and some technical setup. The project also targets users who want to listen across devices while keeping per-user progress, which the README lists as a core feature. For podcast listeners, it offers search and auto-download of episodes, which turns the server into a personal podcast aggregator. The inclusion of basic ebook support (epub, pdf, cbr, cbz) and a send-to-Kindle feature broadens its appeal beyond pure audio, making it a one-stop media hub for readers and listeners alike.

How It Works: Streaming, Metadata, and Library Detection

Audiobookshelf works by scanning a directory structure on your server and treating folder and file names as meaningful metadata. The README warns that directory structure and folder names are important, and it points to library documentation for supported conventions. This means the server does not rely solely on embedded tags; it uses the filesystem layout as a primary source of organization. Once scanned, it streams all audio formats on the fly, which implies transcoding or direct streaming depending on the client capability, though the README does not specify the exact mechanism. The server auto-detects library updates, so you do not need to manually re-scan after adding files. For metadata and cover art, it fetches from several external sources, and for chapter information it uses the Audnexus API. The merge function combines audio files into a single m4b, and it can embed metadata and cover images into the audio files themselves. The server also runs a progressive web app (PWA), which means the web client can be installed on devices. Chromecast support is built into the web app and the Android app, allowing casting to speakers. The system keeps progress per user and syncs across devices, which requires a backend database, though the README does not name the database engine. The open RSS feeds for podcasts and audiobooks suggest that the server exposes subscription URLs, but the README does not detail the feed format or access controls.

Getting It Running: Installation and Development Setup

The README points to installation documentation on the official site, but it also provides a run-from-source guide. For development, the recommended path is a dev container. You need Docker Desktop and VSCode, then install the Remote Development extension and run the command `>Dev Containers: Rebuild and Reopen in Container`. That builds the environment automatically. For a manual setup, you need Node.js version 20 and FFmpeg installed. You must create a `dev.js` file in the project root, using `.devcontainer/dev.js` as an example, to hold configuration and paths unique to your environment. Then you build the client with these commands: `npm ci`, then `cd client`, `npm ci`, `npm run generate`, then `cd ..`. To run the server, use `npm run dev`. The client runs at `localhost:3333` by default, but the port can be changed in `dev.js`. If you modify the client, you must run `(cd client; npm run generate)` and restart the server. For live reloading during client development, you can run `(cd client; npm run dev)` as a separate instance. For production, the README does not give a Docker command, but the installation docs likely cover it. One notable constraint: if you use a reverse proxy with a subfolder, the path must be exactly `/audiobookshelf` and it is not changeable. Also, the server requires a WebSocket connection, so your reverse proxy must be configured to forward WebSocket upgrades.

Genuine Limitations and Failure Modes

Audiobookshelf has several limitations that may make it the wrong tool for some users. First, the ebook support is basic: it handles epub, pdf, cbr, and cbz, but it is not a full ebook management system. The README calls it basic, so do not expect advanced features like annotations, bookmarks, or complex metadata editing for ebooks. Second, the frontend is in transition. The README explicitly states that frontend pull requests for the existing Vue frontend are not being reviewed or merged because the frontend is being rewritten in React. This is a significant risk for anyone who wants to contribute or customize the UI; you may be working on a deprecated codebase. Third, the reverse proxy subfolder path is fixed at `/audiobookshelf`, which is a constraint if you want to serve the app under a different path. Fourth, the iOS beta is full due to Apple's 10k tester limit, so iOS users cannot easily test the app. Fifth, the project relies on external services for metadata and chapter lookup; if those services go down or change their APIs, features like chapter lookup will break. Finally, the README warns that folder names and directory structure are important; if you have a messy library, the server may misidentify books or fail to match metadata, leading to manual cleanup.

Real Alternative: Jellyfin and the Difference in Approach

The closest alternative to Audiobookshelf is Jellyfin, an open-source media server that handles video, music, and ebooks, but it does not specialize in audiobooks. Jellyfin's approach is to treat audiobooks as music tracks within a broader media library, which often results in poor handling of chapters, per-book progress, and audiobook-specific metadata. Audiobookshelf, by contrast, is built specifically for audiobooks, with features like chapter lookup, merging into m4b, and per-user progress that Jellyfin lacks. Jellyfin has a more mature plugin ecosystem and a larger community, but it requires more configuration to get audiobook behavior right. If you already run Jellyfin and only occasionally listen to audiobooks, it might be sufficient. But if audiobooks are a primary use case, Audiobookshelf's focused design gives a better out-of-the-box experience. Another alternative is Plex, but it is not fully open-source and requires a paid subscription for some features. The key difference is that Audiobookshelf is purpose-built, while Jellyfin is a generalist that you must bend to fit your needs.

Maintenance and Upgrade Cost

Audiobookshelf is under active development, with v2.36.0 released on 2026-07-27, and the project is not archived. The release cadence (v2.35.0 in May, v2.35.1 in late May, v2.36.0 in July) suggests frequent updates, which means you should expect to upgrade regularly to get bug fixes and new features. The README notes that the frontend is being rewritten from Vue to React, which is a major architectural change that could introduce breaking changes in the UI or API. Upgrading may require re-testing your reverse proxy configuration, especially since WebSocket connections are essential. The project uses a `dev.js` file for development configuration, but production upgrades likely follow standard Node.js or Docker image updates; the README does not specify a migration path. The license is GPL-3.0, which means if you modify the server and distribute it, you must release your changes under the same license. This is relevant for organizations that want to embed Audiobookshelf in a proprietary product; that would not be allowed without open-sourcing the derivative work. For personal use, this is rarely an issue. The project also depends on external services like Audnexus for chapter lookup, so you must monitor the availability of those services. Backup is built-in with automated daily backups, which is a plus, but you should verify that the backup includes your database and metadata, not just the media files.

Point of View: The Trade-Offs You Should Accept

Audiobookshelf is a strong choice for a niche but active community, but it is not without trade-offs. The biggest trade-off is the frontend rewrite: the project is investing in React, but until that migration is complete, the Vue frontend is in a state of limbo. If you are evaluating this project for a long-term deployment, you should factor in the possibility of UI changes and potential regressions. The fixed subfolder path is another annoyance; if you want to serve the app under a custom path, you will need to use a subdomain or a different reverse proxy strategy. The reliance on directory structure for metadata means that your library organization is part of the system's correctness. This is a design choice that gives you control, but it also puts a burden on you to maintain consistent naming. The project's strength is its focus: it does audiobooks and podcasts well, and it does not try to be a video server. That focus is what makes it better than general-purpose media servers for this use case. But that focus also means it lacks features that a generalist might have, like video streaming or advanced ebook management. If you accept these trade-offs, Audiobookshelf is a capable tool.

Editorial conclusion

Adopt Audiobookshelf if you want a free, open-source, self-hosted server for audiobooks and podcasts with multi-user progress sync, metadata fetching, and built-in ebook support. Avoid it if you need a mature ebook management system, if you rely on the Vue frontend for custom modifications (since it is being rewritten), or if you cannot tolerate the fixed subfolder path for reverse proxies. Before deploying, verify that your audio file naming and directory structure conform to the library documentation, confirm that your reverse proxy supports WebSocket connections, and check the current status of the React frontend migration and any breaking changes in recent releases.

Official sources

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