BookWyrm

Last reviewed Sep 13, 2026 · 829 words

Run BookWyrm for a book club, a library, a school, or a circle of friends who already talk about books, and it is one of the most charming things on the Fediverse. Run it for yourself alone and you have deployed PostgreSQL, two Redis instances, a Celery worker and a Django app so that one person can shelve novels. The catalogue's 2,048 MB floor is real, the AGPL-3.0 licence is fine, and the 2,779 stars reflect a project with a devoted maintainer team. The decision is about people, not software: BookWyrm is social first, and a single-user instance gives up most of the point.

Why it is not a reading app and what that means

BookWyrm tracks reading, reviews, quotes, shelves and yearly challenges, and it federates over ActivityPub so your reviews appear in Mastodon timelines and Mastodon users can follow you. It does not store, open or sync ebooks. If your goal is a library of EPUBs with a reader, that is Calibre-Web or Kavita, and the two combine well: Kavita holds the files, BookWyrm holds the opinions. The ebooks category has the rest of the field.

Book data comes from connectors. A fresh instance can pull metadata from OpenLibrary and Inventaire, and it also learns books from other BookWyrm instances as they federate, so a new server is not starting from an empty catalogue. Cover and edition quality varies wildly, and part of the daily reality of running an instance is people fixing editions by hand.

Deployment is a script, but read the .env first

The repository ships a Compose file and a helper script, bw-dev, that wraps the common operations. The working sequence:

git clone https://github.com/bookwyrm-social/bookwyrm.git
cd bookwyrm
cp .env.example .env
# set DOMAIN, SECRET_KEY, EMAIL_* and the two Redis passwords
docker compose build
./bw-dev migrate
./bw-dev initdb
docker compose up -d

Set DOMAIN before the first migration and never change it afterwards; ActivityPub identities are tied to it, and renaming a federated server breaks every remote follow. Outbound email is not optional either, since registration confirmation, password resets and invites all go through it, so configure an SMTP relay or a transactional provider before inviting anyone. The Compose stack includes nginx and a Certbot container for TLS; if you already run Caddy or Traefik, disable those two and proxy to the web container instead.

Once up, run ./bw-dev admin_code to get the one-time code that turns the first registration into the admin account, then in the admin panel decide on registration mode. Invite-only is the correct default for a small instance; open registration on a federated server means moderation work from day one.

Imports are good, exports are the thing to check

The Goodreads CSV import is the headline feature for switchers and it works, including read dates and ratings, with StoryGraph, LibraryThing, OpenLibrary and Calibre formats supported alongside. Expect a matching pass: an imported title with an ambiguous ISBN lands on a review screen where you confirm the edition. Budget an hour for a 500-book history. In the other direction, BookWyrm can export your data as a CSV and, more recently, as a full user archive for moving between instances; test that export the week you set up, not the week you need it. Our Goodreads alternatives page covers the switching cost in more detail.

Federation costs more than CPU

Every remote follow, boost and review arrives as a background job, so the Celery worker is the component to watch, not the web process. When the worker falls behind, the site looks fine and the federated timeline quietly goes stale. Flower is bundled so you can see the queue depth. A modest instance of 30 to 50 active readers with a few hundred remote follows sits comfortably in the 2 GB the catalogue names; a heavily federated instance with thousands of followed accounts wants 4 GB and a database on SSD.

The other cost is human. Federated content means federated spam and harassment, and the moderation tools (reports, instance blocks, per-user silencing) are adequate but need someone to use them. If nobody on your instance wants to be that person, keep the instance closed and federate cautiously.

What I'd do

For a group of 10 or more readers who already know each other, run BookWyrm on a 4 GB VPS, invite-only, DOMAIN set once, SMTP through a transactional provider, Caddy in front, nightly pg_dump shipped off-box. Import everyone's Goodreads CSVs in the first week while enthusiasm is high. For one person tracking their own reading, do not run it: join an existing public instance, or keep a shelf in Calibre-Web and skip the social layer entirely. BookWyrm is at its best as the thing a small community owns together, and at its worst as another daemon for one.