Chaptarr: a Readarr fork for audiobooks and eBooks in one library

The gap Chaptarr fills: narrator and edition metadata

General-purpose media managers treat a book as one file with one title. Audiobook libraries do not work that way. The same title exists as an M4B, as a folder of MP3 chapters, and as an eBook, each with a different publisher, a different narrator, and a different release date. Chaptarr is a Readarr fork built specifically to hold both audiobook and eBook libraries in one instance, and its key features list is organised around exactly that: narrator awareness, multi-edition support for keeping an audiobook and an eBook of the same title, publisher-aware handling for dramatized audiobooks and multi-part releases, and support for M4B, MP3 chapters and multi-file audiobooks.

The intended user is someone already comfortable with the *arr family. The README states that Chaptarr works with the usual *arr-family download clients and indexer protocols, so the download-client and indexer configuration will look familiar. The project is explicit that it is independent: it is not affiliated with the Servarr team or with Readarr, Sonarr, Radarr, Lidarr or Prowlarr. That matters less for the UI, which is a fork, and more for the metadata layer, which is not.

A metadata pipeline that Readarr installs cannot reuse

The most consequential design decision in Chaptarr is the one stated plainly in the README: Chaptarr is not compatible with Readarr's metadata sources. Instead it uses its own modular pipeline that resolves entities across metadata providers and aggregates their data through what the README calls automated refinement and consensus. In other words, the same author or series may be represented differently by different providers, and Chaptarr's job is to decide which record wins and merge the rest into it.

That approach is the reason narrator and edition fields can exist at all, since a single provider rarely carries them consistently. It is also the reason migration from Readarr is not a database copy. If you have spent time correcting author records or series ordering in Readarr, that work lives in Readarr's schema and its provider mapping, and the README does not describe an import path for it. Treat a Chaptarr install as a new library that needs its own matching pass.

The README is candid about the maturity of this layer: it calls the consensus work an ongoing effort and says it is the core of the project's mission. A pipeline that merges providers is only as good as its tie-breaking rules, and the README does not document how conflicts between providers are resolved or how a user can override a bad merge beyond the ordinary metadata editing the UI provides.

Running Chaptarr in Docker on port 8789

Docker is currently the only supported way to run Chaptarr. The README says releases do not include native install packages, that earlier zip attachments were incomplete build artifacts and have been withdrawn, and that native support starting with an experimental Windows build is being worked on. So the install path is a container pull and run, exposing port 8789.

The README gives this run command, which mounts config, audiobooks, ebooks and downloads and sets the user and group the container runs as:

docker run -d \
  --name chaptarr \
  -p 8789:8789 \
  -e PUID=1000 \
  -e PGID=1000 \
  -v /path/to/config:/config \
  -v /path/to/audiobooks:/audiobooks \
  -v /path/to/ebooks:/ebooks \
  -v /path/to/downloads:/downloads \
  --restart unless-stopped \
  chaptarr/chaptarr:latest

After that, the web interface is on port 8789 of the host. The compose route is shorter if you prefer editing a file: the README suggests fetching the project's docker-compose.yml and editing the paths before starting it.

wget https://raw.githubusercontent.com/chaptarr/chaptarr/develop/docker-compose.yml
# Edit paths in docker-compose.yml
docker compose up -d

Permissions are the first thing that goes wrong, and the README addresses it directly. If PUID and PGID are not set, the image defaults to 99:100. If the config path does not exist, Docker creates it as root:root, so create it first or fix ownership to match PUID and PGID. Do not set user: in Compose, because that bypasses the entrypoint permission setup. On Unraid, media folders commonly use 99:100, so PUID=99 and PGID=100 unless your share is owned differently. When several containers or users share a media group, add UMASK=002. To check writes as the app user rather than as root, the README gives this test:

docker exec -u 99:100 chaptarr sh -c 'id; touch /audiobooks/.chaptarr-write-test && rm /audiobooks/.chaptarr-write-test'

If that command fails, the container will fail to import or rename files later, and the error will surface as a failed import rather than a permissions message.

PostgreSQL, SQLite and the databases Chaptarr will not create for you

By default Chaptarr stores its state in a SQLite file named chaptarr.db. It can instead use an external PostgreSQL server, which is configured entirely through environment variables prefixed with Chaptarr__Postgres__. At minimum you set Chaptarr__Postgres__Host, plus credentials. The defaults are port 5432, user-supplied user and password, and three databases named chaptarr-main, chaptarr-log and chaptarr-cache.

The constraint that catches people out is stated in the README: Chaptarr does not create PostgreSQL databases automatically. You create the three databases and grant the configured user access before starting the container. There is no fallback to SQLite if the connection fails, and the README does not describe what happens to an existing chaptarr.db when you switch to PostgreSQL. Decide on the backend before the first import, not after.

The split into a main, a log and a cache database is worth noting because it tells you the log database grows independently of your library. Anyone running PostgreSQL for Chaptarr should watch that database's size separately from the main one.

MP3 to M4B conversion and what it depends on

Chaptarr can optionally convert MP3 audiobooks into a single chaptered M4B, preserving existing chapters or inserting them when missing. The README attributes that conversion to m4b-tool, an external project, so the quality of the result depends on that tool and on the chapter metadata already present in the source files. If your MP3 rips have no chapter marks, the conversion has to insert them, and the split points will be whatever the tool infers rather than what the release intended.

The README also notes that when running Chaptarr natively, you must install FFmpeg yourself and make sure both ffmpeg and ffprobe are on the PATH used to start Chaptarr, because normal source builds do not bundle them. The official Docker image already includes them. That is one more reason the Docker path is the supported one: a native build with a missing ffprobe fails at the point of media inspection, not at startup.

Building from source is documented for Linux, macOS and Windows and requires the .NET 10 SDK, Node.js and Yarn. The backend is published from src/NzbDrone.Console/Chaptarr.Console.csproj for net10.0, the frontend is built with Yarn, and the resulting UI folder is copied into the publish output. The README notes an inconsistency to watch for: the assembly is named Chaptarr.dll on Linux and macOS but Chaptarr.Console.dll on Windows.

Chaptarr versus Readarr and Bindery

The obvious comparison is Readarr, since Chaptarr is a fork of it. The difference is not the interface, which will look familiar, but the metadata layer and the library model. Readarr's metadata sources cannot be used by Chaptarr, and Chaptarr adds narrator fields, multi-edition handling and audio-format awareness that Readarr does not attempt. If you are leaving Readarr because it stopped tracking the fields you care about, that is the reason to move. If you are leaving because you want a project with a different maintenance story, note that Chaptarr describes itself as beta software under active development, with bugs likely and breaking changes possible.

Bindery is a different kind of answer to the same problem. It is a standalone book manager rather than a fork of an *arr application, so it does not inherit the *arr download-client and indexer conventions that Chaptarr's README leans on. If your stack is already built around those conventions, Chaptarr's integration is the shorter path; if you would rather not run another *arr-shaped service, a standalone tool is the alternative to evaluate. The README does not compare Chaptarr to Bindery, so that distinction comes from what each project is, not from a benchmark.

Beta status, backups and the GPL-3.0 licence

The README opens with a warning block: Chaptarr is beta software, under active development, bugs are likely, and breaking changes are less likely but still possible. It then gives a specific disclosure: the last data loss event was in pre-alpha with a tester group of roughly 30 people about 12 months before the README was written, and over the preceding six months the project grew past 11,000 active users with no reported data loss events. That is the project's own account, not an independent audit. The README's advice is to follow good backup practice and avoid pointing it at a library you cannot afford to lose. Take that literally: keep a copy of your audiobook and eBook files outside the volumes Chaptarr mounts, and keep a copy of /config, because chaptarr.db lives there.

The repository is not archived, and the last push was on 2026-09-05, with releases v0.9.958 on 2026-09-04, v0.9.936 on 2026-08-26 and v0.9.929 on 2026-08-16. The version numbers move quickly, which means the upgrade cost is mostly attention: read the release notes before pulling a new image, and pin a tag rather than following latest if you would rather not absorb a change mid-week. The README does not document a rollback procedure, so a downgrade after a schema change is not something the project promises to support.

Chaptarr is licensed GPL-3.0, matching the licence family of the *arr projects it forks. If you modify Chaptarr and distribute it, or run a modified version as a network service for others, the GPL's source-availability terms are the ones to read. Running an unmodified container for your own library is the ordinary case and does not raise the question. This is a description of the licence, not legal advice.

Editorial conclusion

Chaptarr is for people who already run an *arr stack and need one instance to hold both audiobook and eBook editions of the same title, with narrator and edition metadata that Readarr does not model. It is not for anyone who wants a stable release: the README calls it beta software, Docker is the only supported runtime, and it is not compatible with Readarr's metadata sources, so an existing Readarr database cannot be carried over. Verify three things before pointing it at a library you care about: that the container user can write to /audiobooks and /ebooks, that your metadata provider coverage is adequate for your catalogue, and that you have a backup outside the config volume, because the README's own advice is to avoid pointing it at a library you cannot afford to lose.

Frequently asked questions

Official sources

1. Chaptarr/chaptarr on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases