How to Use BookWyrm: The Beginner’s Guide (First Instance, the Import Lesson, First Shelf, and the Federation Arc)

CodexFuse Team · 2026-11-02T07:35:05.850Z · 14 min read min read

Learn how to use BookWyrm: join an instance, import your Goodreads library as CSV, build shelves, set reading goals, and federate with Mastodon.

If you have spent years building a Goodreads library and now flinch every time Amazon reshuffles the features you rely on, you are exactly who this guide is for. BookWyrm is a federated, reader-run alternative to Goodreads, and learning how to use BookWyrm takes one afternoon: pick an instance, create an account, import your existing library as a CSV, and start shelving, rating, and reviewing like you always did — except your data stays under your control and your recommendations come from people, not an engagement algorithm. This BookWyrm tutorial is the unified beginner walkthrough the field is missing: everything below was verified against the project’s current docs, its instance directory, and a real migration diary, so you can follow it end to end.

One clarification before we start, because the name is crowded: this guide covers the social reading network at bookwyrm.social and joinbookwyrm.com — not the children’s bookstore, TTRPG club, or plush toy that share the name, and not the unrelated AI package called bookwyrm on PyPI. BookWyrm is pre-1.0 software (v0.9.4 as of late October 2026) created by Mouse Reeve and described by its own developers as “Social reading and reviewing, decentralized with ActivityPub.” It ships under the Anti-Capitalist Software License v1.4, which makes it free for individuals and non-capitalist organizations.

This beginner’s walkthrough covers the whole arc: joining an instance, setting up your profile and reading goal, importing your Goodreads CSV, building shelves, writing reviews, and federating with the wider fediverse. If you have never used federated software before, our Lemmy beginner guide explains the one-server-among-many model in five minutes; BookWyrm works the same way, for books. The honest pitch for BookWyrm is human recommendations: finding your next book because a real reader with your taste loved it, instead of because an algorithm pushed a bestseller.

What Is BookWyrm, Exactly?

BookWyrm is the leading federated Goodreads alternative: a decentralized social reading platform built on the ActivityPub protocol — the same open protocol that powers Mastodon. Instead of one company’s website, BookWyrm is a network of independently run servers (“instances”): you join one, and you can still follow and interact with readers on any other instance, because the servers talk to each other. On BookWyrm you track what you read, rate and review books, build themed lists, and see reviews aggregated from readers across connected instances — all in an ad-free interface with no corporate owner. Book data comes from Wikidata and Inventaire, another fediverse project, so the catalogue is community-maintained rather than scraped for ads.

BookWyrm vs Goodreads: What’s the Real Difference?

The short answer is ownership: Goodreads is owned by Amazon and monetizes your reading data; BookWyrm is reader-run software that federates like email, with no ads and no algorithm deciding what you see. The table below lays out the practical differences a switching reader will feel in the first week.

The trade-off is maturity: BookWyrm is pre-1.0 and community-maintained, so expect a smaller catalogue edge case here and there (and a manual-add flow for truly missing books) in exchange for a reading life that no retailer can restructure or shutter.

How Do You Use BookWyrm? The 7-Step Beginner Arc

Here is the full path from stranger to settled reader, in the order you will actually do it. Each step is explained in its own section below.

1. Pick an instance from the directory at joinbookwyrm.com/instances — a small community you trust beats the biggest server.
2. Create your account on that instance’s website and set up your profile.
3. Set a reading goal from Your Profile > Reading Goal so the year has a target.
4. Export your library from Goodreads (My Books > Import and export > Export Library) and save the CSV.
5. Import the CSV into BookWyrm via Settings > Data > Import, then check Import Status while it works.
6. Build your first shelves and lists — the defaults cover the basics, custom shelves cover everything else.
7. Federate: follow readers on other BookWyrm instances and Mastodon users, and let the reviews come to you.

Step 1: How Do You Pick a BookWyrm Instance?

The one lesson that matters here: join a small, trusted community, not necessarily the flagship. Because BookWyrm is federated, you can follow and interact with readers on any instance no matter which one you call home — in the project’s own words, “you can follow and interact with people from other servers, so it doesn’t matter if you and your friends sign up on different servers.” Your instance is mostly your home base, your local timeline, and the admins you trust with your data.

Start at the official directory, joinbookwyrm.com/instances, which lists instances by language and theme. At the time of writing it included options like this:

Check the directory for current registration status before you commit — registration opens and closes per instance, and status varies over time. Pick one whose language, theme, and rules fit you; you can always move later, and your follows reach across the whole network either way.

Step 2: How Do You Set Up Your Account and Reading Goal?

Sign up directly on your chosen instance’s website — there is no central BookWyrm account, so your login lives on your home server. Fill in your profile (display name, bio, avatar) the way you would anywhere; this is the identity other instances will see when you review and comment.

Then set your annual reading goal before you touch a book. As a new user you will see a prompt to set it when you start; otherwise navigate to Your Profile > Reading Goal. A goal does two things: it gives your profile a progress tracker readers can see, and it gives you a reason to open the app in January instead of scrolling somewhere else. One honest warning: the goal is self-reported honor system, like Goodreads — nobody is auditing your page counts.

Step 3: How Do You Import Your Goodreads Library into BookWyrm?

This is the lesson that makes or breaks a migration, and it is the step most people dread — so here is the good news: it is a CSV upload, not a manual re-entry marathon. One migrating reader imported more than 700 books in about two hours, with a handful needing manual review afterward. That is the realistic expectation: mostly automatic, slightly supervised.

First, export from Goodreads: go to My Books > Import and export > Export Library, and download the CSV file Goodreads generates. This BookWyrm import Goodreads walkthrough covers the CSV route because it is the only officially documented path, and it works the same whether your library holds fifty books or five thousand. Then, in BookWyrm, click your account icon for the main menu, choose Settings, select Data > Import, pick Goodreads as the data source, browse to your CSV, choose your privacy setting for imported reviews, and click Import. BookWyrm also imports from LibraryThing, StoryGraph, OpenLibrary, and Calibre, so whatever your current tracker is, the door is probably open.

After you click Import, do not just close the tab: check Import Status in the same area to see which books matched cleanly and which need your attention. Failed or ambiguous matches show up there, and that is where you fix them — this is the “slightly supervised” part. Give a big library time; the importer works through it, it does not do it instantly.

How Do BookWyrm Shelves Work?

Shelves are BookWyrm’s version of Goodreads shelves, and they come with four defaults: “to-read,” “currently reading,” “stopped reading,” and “read.” Your imported books land on these automatically, and from there you organize however you like. Create custom shelves for genres, moods, years, or that “books my sister keeps recommending” pile — shelves are yours to design.

Two details make shelves smarter than plain lists: BookWyrm stores started, stopped, and finished reading dates on each entry, and you can post progress updates as you go (the “on page 214 and the plot just twisted” kind). For curation beyond shelves, use Lists: they support closed, curated, open, and group-edited modes with public, unlisted, followers-only, or private visibility, and groups can collaborate on group-owned lists. Lists are the tool for “best cozy mysteries of 2026”; shelves are the tool for your personal reading state.

How Do You Write Reviews That Actually Reach People?

On BookWyrm you compose reviews with or without ratings, and the book’s page aggregates reviews from readers across connected instances — so your review sits in a genuinely multi-community conversation, not one site’s comment section. Beyond reviews, you can post comments and quotes or excerpts from books, which makes the timeline feel like a book club that never adjourns rather than a star-rating database.

The practical advice: write the review you wish you could read before starting the book. Because BookWyrm has no engagement algorithm boosting bestsellers, your review of a quiet midlist novel can actually be the thing that puts it on another reader’s radar — one reviewer put it well, calling BookWyrm a place to “find new books based on recommendations from real people instead of algorithms pushing bestsellers.” Rate honestly, shelve precisely, and follow readers whose taste overlaps yours; the feed does the rest.

How Does Federation Work on BookWyrm?

Federation is the part that sounds technical and feels magical once it works. BookWyrm speaks ActivityPub, which means your BookWyrm account is not trapped on your instance: readers on other BookWyrm servers can follow you, and — the part newcomers love — people on Mastodon can follow your BookWyrm account too, and your reviews will appear in their Mastodon timelines where they can read and comment. In the project’s own phrasing, “your friend on mastodon can read and comment on a book review that you post on your BookWyrm instance.”

Practically, this means three things for a beginner. First, your audience is bigger than your instance — follow interesting reviewers wherever they live. Second, your posts travel: a review you write can surface in a Mastodon follower’s feed without them ever visiting BookWyrm. Third, discovery compounds: the book pages show aggregate reviews across connected instances, so a book’s reception reflects the whole federated reading community, not one server’s bubble. If the fediverse model is new to you, our Lemmy beginner guide walks through the same follow-across-servers mechanics for forums.

Is There a BookWyrm App?

Here is the honest answer the cluster keyword deserves: there is no official native BookWyrm app. What exists is the official BookWyrm web app, which you can install on Android or iPhone/iPad as a progressive web app — it behaves like an app (icon on your home screen, full-screen reading interface) without a trip to an app store. There is also an unofficial Android client on F-Droid, but its own description warns that it is a webview wrapper and “not an official client.”

For most readers the installable web app is the right answer: you get the full BookWyrm experience — shelves, reviews, goals, federation — without waiting for a native client that does not exist yet. Bookmark your instance, install it to your home screen, and treat it like your reading app.

How Do You Self-Host BookWyrm?

If “reader-run” appeals to you enough to run the server yourself, a BookWyrm self hosted instance installs with Docker and docker-compose. The official production path is: clone the repository with our Git beginner guide commands, copy .env.example to .env, run ./bw-dev setup, then docker-compose up -d. If Docker is new to you, start with our Docker beginner guide; you will want a VPS with a public domain, which is where what VPS hosting actually is comes in.

One caution, stated once and plainly: the project itself warns that BookWyrm “is still young and isn’t, at the moment, very stable, so please proceed with caution when running in production.” Self-host for the learning and the independence, keep backups of your database, and do not promise your book club five-nines uptime. For most beginners, joining an existing instance is the right first move; self-hosting is the graduation project.

7 Beginner Mistakes to Avoid on BookWyrm

Every one of these comes from real migration stories and the project’s own docs. Skim them before your first import and you will skip the whole learning-curve tax.

Sources

1. BookWyrm instances directory — https://joinbookwyrm.com/instances/
2. BookWyrm user documentation — https://docs.joinbookwyrm.com/
3. BookWyrm main menu and reading goals docs — https://docs.joinbookwyrm.com/main-menu.html
4. BookWyrm production installation docs — https://docs.joinbookwyrm.com/install-prod.html
5. BookWyrm lists documentation — https://docs.joinbookwyrm.com/lists.html
6. fedi.tips BookWyrm FAQ (instances, import, manual add, apps, federation) — https://fedi.tips/tag/bookwyrm/
7. fedi.tips: manually adding a book on BookWyrm — https://fedi.tips/how-to-manually-add-a-book-on-bookwyrm/
8. BookWyrm GitHub repository (description, license, releases) — https://github.com/bookwyrm-social/bookwyrm
9. BookWyrm v0.9.4 release notes — https://github.com/bookwyrm-social/bookwyrm/releases/tag/v0.9.4
10. Goodreads library export help — http://help.goodreads.com/s/article/000001100
11. Noisy Deadlines: migrating book tracking to BookWyrm — https://noisydeadlines.net/moving-my-book-tracking-to-bookwyrm
12. GetFreeEbooks: Goodreads alternatives (BookWyrm section and name disambiguation) — https://getfreeebooks.com/goodreads-alternatives-book-tracking/

Frequently Asked Questions

Is BookWyrm really free?

Yes for readers: joining an instance costs nothing, and the software is released under the Anti-Capitalist Software License v1.4, free for individuals and non-capitalist organizations. Individual instances may accept donations to cover their hosting, which is how reader-run servers stay alive.

Can I move my Goodreads library to BookWyrm?

Yes — export your Goodreads library as a CSV (My Books > Import and export > Export Library), then import it in BookWyrm under Settings > Data > Import. One migrating reader moved 700+ books in about two hours, then reviewed the Import Status report to fix ambiguous matches. BookWyrm also imports from LibraryThing, StoryGraph, OpenLibrary, and Calibre.

Do I need to be on the same instance as my friends?

No. BookWyrm is federated like Mastodon: you can follow and interact with readers on other servers regardless of where anyone signed up. Your instance is your home base and your local timeline, not a wall around your social life.

Can Mastodon users see my BookWyrm reviews?

Yes. Because BookWyrm speaks ActivityPub, people on Mastodon and other compatible services can follow your BookWyrm account, and your reviews appear in their timelines where they can read and comment. Federation is the feature that makes one review reach readers who never visit BookWyrm.

Is there a BookWyrm app for iPhone or Android?

There is no official native app. Install the official BookWyrm web app to your home screen (it works as a progressive web app on both Android and iPhone/iPad), or try the unofficial F-Droid wrapper on Android — its own listing warns it is not an official client.