Calibre-Web-NextGen (CWNG) is a self-hosted ebook library you use from a browser, an e-reader or any OPDS app. It's built on Calibre-Web-Automated (CWA) and works as a drop-in replacement for its Docker image. Community fixes and new features ship in frequent releases.
Change one line in your compose file:
- image: crocodilestick/calibre-web-automated:latest
+ image: ghcr.io/new-usemame/calibre-web-nextgen:latestThen pull and recreate the container:
docker compose pull && docker compose up -dYour library, settings, users, OAuth tokens and KOReader sync state live in your volumes and carry over. To switch back, reverse the line.
Run Docker from a NAS or a web UI instead of a terminal? Follow the step-by-step guide for your platform. Each one covers a fresh install and a switch from CWA, button by button: Synology · Unraid · Portainer · TrueNAS SCALE · all guides. If your screens don't match, open an issue or ask on Discord.
- New install? Start with the Quick start.
- Found a bug? File it here.
- Have an idea, even a half-formed one? Open a feature request. No checklist required.
- Setting up with an AI assistant? Point it at
AI_README.md, a guide written for the assistant to follow, verify and hand back to you working. - AI does much of the development work on this fork and none of the work in the app you run. How AI is used explains the review gates.
- Want to back the work? Sponsor on GitHub, one-time or monthly. Nothing is paywalled.
On November 15, 2026, 59 pull requests were open and 1,926 closed, 1,752 of them merged. Of 838 fixes delivered to a person, 34% heard back happy, 10% not fixed and 57% got no reply. When someone did answer, the answer was happy 77% of the time.
A fix is one moment someone was told their problem was dealt with: a fix PR merged for their issue, their issue closed as done, their own PR merged or closed, or our note on an upstream CWA or Calibre-Web thread pointing them to a fix here. Happy means they then said it works or were content with it. Not fixed means they reopened it, said it is still broken in whole or part, or were unhappy with how it went, and every close in a close-and-reopen cycle counts. No reply means nothing came back. Each reply is judged against a written rubric by one model and checked by a second; where they disagree the thread is reread and settled. Every verdict and the quote behind it are in docs/progress-tracker. Replies on Discord and Reddit are not counted.
The numbers by month
| Month | PRs opened | PRs closed | Open, daily average | Happy | Not fixed | No reply |
|---|---|---|---|---|---|---|
| May 2026 | 270 | 266 | 2 | 38 | 16 | 169 |
| Jun 2026 | 168 | 168 | 4 | 32 | 13 | 26 |
| Jul 2026 | 359 | 362 | 3 | 107 | 26 | 70 |
| Aug 2026 | 578 | 573 | 11 | 35 | 14 | 71 |
| Sep 2026 | 224 | 218 | 12 | 23 | 5 | 32 |
| Oct 2026 | 279 | 241 | 35 | 37 | 5 | 73 |
| Nov 2026 | 107 | 98 | 56 | 9 | 4 | 33 |
Regenerate with python3 scripts/progress_tracker.py fetch, then queue, judge the new replies, apply and render.
Prefer separate pages with a sidebar? The same guides are on the searchable docs site and in the project wiki.
- Why this fork exists
- What's included
- Quick start
- Full Docker Compose setup
- NixOS
- First run
- Updating
- Migrating
- Pair with Shelfmark
- Common configurations
- Troubleshooting
- Differences from upstream
- Translations
- Contributing
- Supporting the project
- How AI is used
- Credits
The goal is to get fixes to users quickly. Community pull requests, including ones waiting in CWA's queue, are reviewed and merged here, and bugs reported here get fixed whether or not someone has sent a patch. Feature work follows what people ask for in the issue tracker, and all of it ships in regular releases.
The data format and configuration match upstream CWA, so switching images is reversible and needs no migration in either direction.
CWNG is built on CWA and adds the changes listed in CHANGES-vs-upstream.md. Some you'll notice:
- A redesigned interface, the New UI, with the Classic interface still available.
- On a Kindle or any e-reader running KOReader, the plugin opens on your library's covers, downloads a book when you tap it, and syncs position, read status and highlights back. See Your library on a Kindle.
- Kobo sync of the shelves you choose, which appear on the device as collections. See Choosing which books go to your Kobo.
- Reading status, ratings and private reviews kept per account.
- Sharper covers for high-DPI e-readers, a cover designer for books that have none, and ISBN lookup inside book files.
- Book sources (Beta): request books from OPDS catalogs and Newznab/Torznab indexers and have them imported through the normal ingest. New UI only, off by default.
- A Docker healthcheck that also fails when the library database, the ingest service or the metadata-change service is down.
- An update helper in the app that gives the exact update command for your setup.
You need Docker with Docker Compose.
-
Make folders for your library:
mkdir -p ~/calibre-web/{config,library,ingest} cd ~/calibre-web
-
Save this as
docker-compose.yml:services: calibre-web: image: ghcr.io/new-usemame/calibre-web-nextgen:latest container_name: calibre-web environment: - PUID=1000 - PGID=1000 - TZ=America/New_York # change to your timezone volumes: - ./config:/config # settings, user db, logs - ./library:/calibre-library # books live here - ./ingest:/cwa-book-ingest # drop new books here to import ports: - 8083:8083 restart: unless-stopped
-
Start it:
docker compose up -d
-
Open
http://localhost:8083, sign in asadmin/admin123, and change the password.
Drop an .epub into ./ingest/ and it shows up in your library within a few seconds.
Files in your library and ingest folders should belong to your
PUID:PGIDuser (1000 by default), not root. If you copied books in as root, fix that once withsudo chown -R 1000:1000 ~/calibre-web.
A fuller compose file, with a comment on each option:
services:
calibre-web:
image: ghcr.io/new-usemame/calibre-web-nextgen:latest
container_name: calibre-web
environment:
# Match your host user and group (run `id` to see them) so the
# container and the host can both write to your library.
- PUID=1000
- PGID=1000
# https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
- TZ=America/New_York
# Port inside the container. If you set it below 1024,
# also uncomment cap_add below.
- CWA_PORT_OVERRIDE=8083
# Set to true if /config or /calibre-library is on an NFS or
# SMB share. See "Network shares" below.
- NETWORK_SHARE_MODE=false
# How many proxies sit in front of the container (for example
# Cloudflare Tunnel, then nginx), so session protection sees
# the real client IP. Default 1.
- TRUSTED_PROXY_COUNT=1
# Optional: token for the Hardcover metadata provider.
# Free at https://hardcover.app/account/api
# - HARDCOVER_TOKEN=eyJhbGciOiJIUzI1NiI...
# Optional: your own ComicVine API key. Without one, ComicVine
# uses a key shared by every install and can hit its rate limit.
# Free at https://comicvine.gamespot.com/api/
# - COMICVINE_API_KEY=...
# Optional: paths inside the container. The volume targets
# below must use the same paths.
# - CWA_INGEST_FOLDER=/cwa-book-ingest
# - CWA_CALIBRE_LIBRARY_DIR=/calibre-library
# - CWA_TMP_CONVERSION_DIR=/config/.cwa_conversion_tmp
volumes:
# Settings, user database, logs. New install: an empty folder.
# Coming from CWA: your existing /config.
- /path/to/config:/config
# Your Calibre library. New install: an empty folder, and CWNG
# creates a library in it. Existing library: the folder that
# holds metadata.db.
- /path/to/library:/calibre-library
# Drop new books here to import them. WARNING: files in this
# folder are DELETED after processing. Never point it at a
# folder you also use for long-term storage.
- /path/to/ingest:/cwa-book-ingest
# Optional: bind your existing Calibre plugins folder
# - /path/to/calibre-plugins:/config/.config/calibre/plugins
ports:
- 8083:8083
# Uncomment if CWA_PORT_OVERRIDE is below 1024.
# cap_add:
# - NET_BIND_SERVICE
restart: unless-stopped| Volume | What it holds | Notes |
|---|---|---|
/config |
App settings, user accounts, OAuth tokens, KOReader sync state, logs | Empty folder for a new install. Carries over from CWA as is. |
/calibre-library |
Your books and Calibre's metadata.db |
If it's empty, CWNG creates a new library. If it holds several metadata.db files, CWNG uses the largest. |
/cwa-book-ingest |
Drop zone for new books | Files here are deleted after processing. Don't keep books here. |
Keep all three as separate top-level folders. Nesting ingest inside library makes ingest run recursively.
Packaging CWNG outside Docker, as a distro package or a systemd service? Runtime path overrides for packagers covers the path variables and dirs.json.
The image is a standard OCI image, so Podman runs it unchanged:
podman run -d --name calibre-web \
-e PUID=1000 -e PGID=1000 -e TZ=America/New_York \
-p 8083:8083 \
-v /path/to/config:/config \
-v /path/to/library:/calibre-library \
-v /path/to/ingest:/cwa-book-ingest \
ghcr.io/new-usemame/calibre-web-nextgen:latestRootless Podman remaps user IDs, so if the container can't write to your volumes, add --userns=keep-id or run it rootful. Podman also has its own automatic updates with rollback (podman auto-update). A step-by-step guide will follow once this recipe has been verified against the image.
The NixOS channel is community-maintained: the Docker image is the supported install, and @BeatLink is the contact for NixOS questions and issues.
The repository is a Nix flake with a package and a NixOS module that runs the web app and its background services as systemd units:
{
inputs.calibre-web-nextgen.url = "github:new-usemame/Calibre-Web-NextGen";
outputs = { nixpkgs, calibre-web-nextgen, ... }: {
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
modules = [
calibre-web-nextgen.nixosModules.default
{
services.calibre-web-nextgen = {
enable = true;
libraryDir = "/srv/books/library";
ingestDir = "/srv/books/ingest";
};
}
];
};
};
}State lives in /var/lib/calibre-web-nextgen (configDir). The library and
ingest folders must already exist and be writable by the service user. On first
start the service creates app.db and an empty library, as the container does.
The web app listens on 127.0.0.1:8083 by default; listenAddress, port,
openFirewall and environment cover the rest.
Alongside calibre-web-nextgen.service, the module starts the ingest watcher,
the metadata change detector, the nightly backup zipper, the cover-preview cache
sweeper and the KOReader checksum backfill as calibre-web-nextgen-* units,
from the same scripts/services bodies the container runs.
nix build builds the package, nix run starts it with state in
~/.calibre-web-automated, and nix flake check runs a NixOS VM test of the
module.
- Open
http://your-host:8083. - Sign in as
admin/admin123. - Change the admin password under Profile → Account.
- Under Admin → Edit Basic Configuration → Feature Configuration, turn on Allow Uploads. Metadata fetch and cover-from-URL need it to write to your library.
- Drop a book into your ingest folder. It appears in the library within a few seconds.
Admin → Settings holds many optional switches: auto-convert formats, automatic backups, the EPUB fixer, KOReader sync, OAuth and more. The upstream CWA wiki documents them. For Generic OIDC credentials and endpoints managed by your deployment, see the environment configuration guide.
Updating means pulling the new image and recreating the container. Your library, settings and reading progress live in the mounted volumes, so they stay as they are.
docker compose pull calibre-web && docker compose up -d calibre-webUse your own service name if it isn't calibre-web. On most NAS web UIs, a restart does not pull a new image. The platform guides show how to update on Synology, Unraid, Portainer and TrueNAS.
To update automatically, run Watchtower (the maintained fork) next to CWNG. The label limits Watchtower to this one container, so your other containers are left alone:
services:
calibre-web:
image: ghcr.io/new-usemame/calibre-web-nextgen:latest
labels: ["com.centurylinklabs.watchtower.enable=true"]
# ...rest of your config
watchtower:
image: nickfedor/watchtower
volumes: ["/var/run/docker.sock:/var/run/docker.sock"]
command: --label-enable --cleanup --interval 86400 # check daily, remove old images
restart: unless-stoppedIn the app, Admin → NextGen Settings → Automatic updates shows the same steps, and the "Update available" banner's Update now button gives the right command for your setup (Compose, docker run, Unraid, Portainer or Synology).
Change the image: line to ghcr.io/new-usemame/calibre-web-nextgen:latest and run docker compose pull && docker compose up -d, as in Switch from upstream CWA. Settings, users, OAuth tokens and KOReader sync state are preserved. The data format is identical, so reverting is the same one-line change in reverse.
- Stop your Calibre-Web container.
- In the new compose file, point
/configat the same folder Calibre-Web used for/config. - Bind whatever was
/booksin Calibre-Web as/calibre-library. - Give
/cwa-book-ingestan empty folder. Stock Calibre-Web has no equivalent. - Start the container.
Users, settings and shelves carry over. The first start takes a few extra seconds while CWNG registers itself with the existing app database.
Shelfmark by @calibrain is a self-hosted book search and request service. It searches torrent, usenet, IRC and direct sources from one page, hands the download to your client of choice, and drops the finished file into CWNG's ingest folder, where it's imported automatically. Requests are multi-user, so household readers can ask for books and you approve them.
CWNG's own Book sources (Beta) covers OPDS catalogs and Newznab/Torznab indexers from the New UI. It has no Anna's Archive provider; for sources it doesn't cover, use Shelfmark.
With My Library on, books that arrive through the shared ingest folder join the global library. The folder doesn't say who requested a book, so it isn't added to the requester's selection automatically. Readers with Global Library access can find it and add it there, and an administrator can add it for a managed account. Accounts in whole-library mode see permitted imports automatically.
Add Shelfmark next to calibre-web in the same compose file:
shelfmark:
image: ghcr.io/calibrain/shelfmark:latest
container_name: shelfmark
environment:
- PUID=1000
- PGID=1000
- TZ=America/New_York
- SEARCH_MODE=universal
# Read CWNG's app.db (read-only mount below) so users sign in
# to Shelfmark with their existing CWNG accounts.
- CWA_DB_PATH=/auth/cw-config/app.db
# Optional: shows a "Library" button in Shelfmark's header
# that links back to CWNG.
- CALIBRE_WEB_URL=http://your-host:8083
volumes:
- /path/to/shelfmark-config:/config
# Your CWNG config folder, read-only, for the sign-in integration.
- /path/to/cwa-config:/auth/cw-config:ro
# Shelfmark's destination folder is CWNG's ingest folder.
# Downloads land here and are imported on the next watch tick.
- /path/to/cwa-ingest:/books
# Using a torrent or usenet client? Mount its downloads folder
# at the same path you mounted in the client itself, so
# Shelfmark can find the completed file.
- /path/to/downloads:/downloads
ports:
- 8084:8084
restart: unless-stoppedOnce Shelfmark is running, open it, choose Settings → Security → Authentication Method → Calibre-Web Database, then Sync from Calibre-Web to import your users. The Shelfmark docs cover Prowlarr, qBittorrent, SABnzbd and IRC setup.
Shelfmark moved to maintenance-only status in May 2026. The v1.3.0 build is stable and its CWA integration is settled, but new feature work has paused. To pin it, use
ghcr.io/calibrain/shelfmark:v1.3.0instead of:latest.
If /config or /calibre-library lives on a network share, set:
- NETWORK_SHARE_MODE=trueThis:
- Turns off SQLite WAL mode, which NFS and SMB don't reliably support. Without it you'll see "database is locked".
- Skips the recursive ownership fix at startup, which is slow on NFS and often fails on SMB.
- Switches the ingest watcher from inotify to polling, because inotify events are unreliable on network filesystems.
It's tested and supported. Ingest is a few seconds slower; everything else behaves the same.
Files owned by root after a copy? CWNG chowns files back to your
PUID:PGIDafter each metadata-change cycle. For files you copied in as root before upgrading, run once:docker exec calibre-web chown -R abc:abc /calibre-library(replaceabcif you've customized the user).
examples/.env.example lists every environment variable with its default.
On macOS with Docker Desktop, give native Mac Calibre the library to itself. If the library is a host bind mount, stop the CWNG container before you open it in Mac Calibre or run native calibredb, and quit Mac Calibre completely before you start the container again. Stopping ingest alone isn't enough, because other parts of the app still write to the library.
The flags below don't make simultaneous Mac and container access safe. In a Docker Desktop bind-mount test, an exclusive lock held on one side blocked processes on that side but not on the other, and a concurrent-write test produced a malformed database even with both flags on and the library in DELETE journal mode.
Where desktop Calibre and the server do share working filesystem locks, set both flags:
- NETWORK_SHARE_MODE=true
- DESKTOP_COMPAT_MODE=trueBy default CWNG holds one SQLite connection open for the life of the process. DESKTOP_COMPAT_MODE=true opens one per request instead, so edits, adds and deletes made in Calibre desktop show up in the web UI on the next page load, with no restart. It doesn't replace filesystem locking.
The cost is a little overhead on every request, and a request can wait up to 60 seconds while desktop Calibre is writing. It suits a home server where desktop Calibre comes out now and then for bulk edits, not heavy use of both at once.
CWNG ships no Calibre plugins, but it loads the ones you install: the same .zip files Calibre desktop uses, such as DeDRM and Obok for DRM removal or ACSM Input for .acsm fulfillment. They run automatically during ingest, library conversion and metadata embedding.
-
Turn the feature on in your compose environment, then restart:
- CWA_CALIBRE_USER_PLUGINS=true -
Copy the plugin
.zipfiles into<your config folder>/.config/calibre/plugins/on the host. The folder appears once the option is on. -
Restart the container again. Each plugin registers at startup; confirm with:
docker logs calibre-web 2>&1 | grep "Registered Calibre plugin"
Plugins that need keys or an account (DeDRM wants your device keys, ACSM Input an Adobe login) keep their settings in files next to the zips. Set the plugin up in Calibre desktop first, then copy its settings files (for example plugins/dedrm.json or the plugins/DeACSM/ folder) from your desktop Calibre configuration into the container's plugins/ folder and restart.
To add another plugin after the first batch has registered, drop its zip in the same folder and run:
docker exec -e HOME=/config calibre-web /opt/calibre/calibre-customize -a "/config/.config/calibre/plugins/<plugin file>.zip"
The feature is off by default because plugins run third-party code inside your container. Install only plugins you trust, from their official release pages; which plugins you use is your call.
How plugins change the book editor's conversion formats, and how .acsm tickets are fulfilled and recovered, is in Calibre plugins: conversion formats and ACSM tickets. If an ACSM import fails, don't delete its entry under processed_books/acsm_fulfilled/: the ticket may already be spent, and that entry holds the fulfilled book.
Behind a proxy, CWNG has to know which forwarded headers to believe. If it gets that wrong, it may see a different client IP on each request and raise Session Protection warnings that force a new sign-in on every page, or mistake an externally secure OIDC callback for plain HTTP.
Set TRUSTED_PROXY_COUNT to the number of trusted proxy hops. The default is 1. Cloudflare Tunnel in front of nginx is 2, and so is HAProxy in front of traefik:
- TRUSTED_PROXY_COUNT=2The count picks which entry in each header to believe. With X-Forwarded-Proto: https, http, 1 selects the inner hop's http and 2 selects the browser-facing https. One count covers X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-Prefix. If your layers append or replace those headers differently, override the first three separately. They map to ProxyFix's x_for, x_proto and x_host, and fall back to TRUSTED_PROXY_COUNT, then 1:
- PROXYFIX_X_FOR=2
- PROXYFIX_X_PROTO=1
- PROXYFIX_X_HOST=1Count only proxies you control that overwrite or sanitize the header in question.
CWNG also checks where the proxy connects from. By default it believes forwarded headers only from this host, private networks (the Docker network and your LAN) and Tailscale's 100.64.0.0/10. A client that reaches CWNG directly from anywhere else is taken at its own address and scheme, whatever headers it sends. If your proxy connects from a public address, add it to TRUSTED_PROXY_NETWORKS. That includes Cloudflare's proxy forwarding straight to the container with no proxy of your own in between: list Cloudflare's published IP ranges.
- TRUSTED_PROXY_NETWORKS=private, 203.0.113.7, 198.51.100.0/24Separate entries with commas or spaces. private stands for the default list, so keep it when you add your proxy. * trusts every peer, which was the behaviour before this setting existed. Without the right entry, CWNG sees every visitor as the proxy: sign-in pacing is shared by everyone, links come out as http:// behind an HTTPS proxy, and sign-in providers may reject the callback address. The log then says Ignoring reverse-proxy headers from <address>.
A Rejected cross-site warning comes from the New UI's API Origin guard. The guard accepts a same-host HTTPS origin even when the proxy-derived URL is HTTP, so TLS terminated upstream doesn't block writes, but an HTTP origin against an HTTPS-derived URL is still rejected. Check TRUSTED_PROXY_COUNT and the forwarded headers first. If the proxy rewrites Host without keeping the public host in X-Forwarded-Host, set CWNG_TRUSTED_ORIGINS to your public origin (comma-separated for several). Generated URLs and other scheme-sensitive behavior still need correct proxy headers.
To serve CWNG under a path such as /cwa/, the proxy forwards requests to the container and strips the prefix, and the app is told what the prefix is. With nginx:
location /cwa/ {
proxy_pass http://calibre-web:8083/;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}The trailing slash on proxy_pass matters: it strips /cwa/ before the request reaches CWNG. The headers are written out instead of pulled in with include proxy_params; because that file ships only with Debian and Ubuntu's nginx package. The official nginx Docker images don't have it, and nginx refuses to start when an include is missing.
Then give the app the external prefix in your compose file:
environment:
- PROXY_SCRIPT_NAME=/cwaLeave the trailing slash off. CWNG joins the value to each path directly, so /cwa/ would generate doubled-slash URLs.
For TLS, upload limits and the larger proxy buffers Kobo sync needs, see examples/nginx-reverse-proxy.conf. Its settings apply to a prefixed deployment too.
Hardcover is a free metadata provider. To turn it on:
-
Sign up at https://hardcover.app and copy an API token from https://hardcover.app/account/api.
-
Add it to your compose environment:
- HARDCOVER_TOKEN=eyJhbGciOiJIUzI1NiI...Or paste it into Admin → Edit Basic Configuration → Hardcover API Key.
-
Restart the container. Hardcover now appears in the Fetch Metadata dialog.
To keep the token out of your compose file, point HARDCOVER_TOKEN_FILE at a file that contains only the token (Docker secrets style):
- HARDCOVER_TOKEN_FILE=/run/secrets/hardcover_tokenA key typed into the admin UI wins, then HARDCOVER_TOKEN, then HARDCOVER_TOKEN_FILE. The Hardcover API Key field shows only a key entered there, so it stays empty when the token comes from the environment. The admin page says which variable is active without showing its value.
There are two Hardcover tokens, and both take the same personal API token from https://hardcover.app/account/api. The one above belongs to the server and is used to look up books (metadata search and Hardcover ID fetching), so it only reads from Hardcover. Each user also has their own Hardcover API Token on their profile page in the classic UI. Sync uses only that one: it writes to that person's Hardcover library (reading progress and status from Kobo and KOReader, books marked as read, and books added to a Kobo-synced shelf). So each reader's token has to come from the Hardcover account whose library should be updated, and replacing the server token does not fix sync when a reader's own token has expired.
If you create a token with limited scopes, these are the ones CWNG uses (Hardcover's scope list):
| Token | Scopes |
|---|---|
Server token (Basic Configuration or HARDCOVER_TOKEN) |
read:catalog, read:me |
| Each reader's own token | read:catalog, read:me, read:library, write:library |
A reader's token needs read:catalog too, because metadata search tries it before the server token and sync looks up the current Hardcover book for an edition before writing.
Turn on Enable Hardcover Sync once under Admin → Edit Basic Configuration. That one switch controls both scheduled Hardcover ID fetching and Kobo/KOReader reading-progress sync. A declarative deployment can set it instead:
- HARDCOVER_SYNC_ENABLED=trueTrue values are true, 1, yes and on; false values are false, 0, no and off, in any case. While the variable is set, the UI shows the effective state and leaves changes to your deployment configuration.
KOReader sync is built in, so you don't need a separate kosync server. With the plugin, a Kindle or any KOReader e-reader opens on your library: covers of every book (or of the shelves you choose for e-readers), each downloaded when you open it, with reading position, read status and highlights synced automatically. Setup and daily use: docs/koreader-kindle.md.
- In CWNG, open E-readers ▸ Pair a Kobo or KOReader and either download the ready-made plugin (copy one folder over USB, nothing to type on the e-reader) or pair with a code shown on the e-reader.
- To install the plain plugin by hand instead, visit
http://your-host:8083/kosync, then sign in from Tools ▸ CWNG library ▸ Connect this device. - Read on any device. Progress syncs back to CWNG, and from there to Kobo if Kobo sync is on.
To keep the plugin updated, use KOReader's Updates Manager or appstore.koplugin and point it at the plugin's own repository, new-usemame/cwngsync.koplugin, not this one. Both update it in place. The plugin is released only when it changes, and its version is the server version it last changed in, so it can trail your server version with nothing wrong. An update manager still pointed at this repository keeps working, but it sees the plugin only on releases that change it, which looks like "no update available". To update by hand, /kosync always serves the plugin bundled with your running server.
Updates Manager. It has no screen for adding a repository, so you add this one by creating a config file:
-
Connect the e-reader over USB and open the
settingsfolder inside KOReader's folder. On a Kobo that is.adds/koreader/settings/(.addsis hidden, so turn on hidden files); on a Kindle it iskoreader/settings/. Repository Settings (step 3) prints the exact path it reads. -
Create a plain-text file there named
updatesmanager_config.json:{ "plugins": [ { "owner": "new-usemame", "repo": "cwngsync.koplugin", "description": "CWNG library sync" } ] }If the file already exists, add the entry to its existing
"plugins"list instead. Your entries are merged with the built-in list. -
Eject the e-reader and restart KOReader. Updates Manager ▸ Settings ▸ Repository Settings should now show
Plugins: 1(or one more than before, if the file already had entries). Then run Check for Updates (Force Refresh the first time, to skip the cache).
If Repository Settings says "No custom configuration file found", the file is misnamed or in the wrong folder: compare it with the path shown there, and make sure the name doesn't end in .json.txt. If it says "File exists but could not be parsed", the JSON is invalid, often because an editor turned the quotes into curly quotes. Without a GitHub token, Updates Manager is limited to 60 GitHub requests per hour. Put a token with public_repo scope in settings/updatesmanager_github_token.txt if checks stall.
appstore.koplugin. Use the gear icon (⚙️) ▸ Install plugin from URL and enter new-usemame and cwngsync.koplugin. If the plugin is already installed, use Match with URL to link it to that repository so updates are tracked.
For matching OPDS filenames across devices, turn on Use server filenames in KOReader's OPDS catalog settings. By default KOReader builds Author - Title.epub from the feed, while the server suggests Title - Author.epub with only the first author. With the setting on, KOReader uses the server's name. Administrators can change that name with the OPDS download filename template preference; a blank preference keeps the current naming. Fields, examples and device limits: OPDS download filenames.
For books emailed to a reader, the eReader attachment filename template in the administrator's email settings sets the attachment name, series and series number included. See Names for emailed book attachments.
Read your library on a Kobo e-reader, with reading progress syncing both ways. Sync runs against your own server, so your library never leaves your network.
- In Admin → Edit Basic Configuration, turn on Enable Kobo sync.
- Open your user page (Admin → Users → your user, or your own profile) and click Create/View next to Kobo Sync Token. The dialog shows the exact
api_endpoint=line for your account. - Connect the Kobo to a computer over USB and open
.kobo/Kobo/Kobo eReader.confin a text editor. Add or replace theapi_endpoint=line with the one from the dialog, save, and eject the device cleanly. - Sync on the Kobo. Books on your Kobo Sync shelves appear on the device, and progress flows back to CWNG.
To choose which shelves reach the device, see Choosing which books go to your Kobo. To confirm the device is reaching your server, watch for requests to /kobo/<token>/v1/... while it syncs:
docker logs -f calibre-web 2>&1 | grep /kobo/Don't hand-edit
reading_services_hostin the conf file.api_endpointroutes library sync. Highlights and notes travel over a separate reading-services channel set byreading_services_host. CWNG advertises the right value during sync initialization, and a device that does a full initialization against your server adopts it on its own.A hand edit has been measured to break syncing outright. A Kobo Clara BW on firmware 4.42.23291 failed every sync with
FailedSync / WebRequestErruntil the key went back toreadingservices.kobo.com. A Kobo Libra Colour on 4.45.23697 is unaffected and routes annotations through CWNG, but there's no way yet to predict which devices tolerate the edit, and a device that fails can't sync and shows no obvious cause.If sync broke after you edited that key, set
reading_services_hostback toreadingservices.kobo.com, save, eject cleanly and sync again.To see whether highlights reach CWNG, make one on the device, sync, and watch:
docker logs -f calibre-web 2>&1 | grep -iE "annotations|reading services"Silence means your highlights are going to Kobo's servers instead of yours. To change that safely, regenerate the Kobo Sync Token and re-pair so the device does a full initialization against CWNG. This matters because CWNG's protection against a Kobo deleting its own highlights after a sync (upstream calibre-web#2610) works by answering that channel, and it can't protect a request it never receives. Until a device routes annotations through CWNG, treat highlights made on it as device-only and back them up.
Kobo devices sync over HTTPS, so api_endpoint has to be your public https:// address. Put a proxy with a valid certificate (nginx, Nginx Proxy Manager, Caddy or Cloudflare Tunnel) in front and point it at the container's plain HTTP port:
- The proxy target is
http://<container-host>:8083. The proxy terminates TLS on 443, and the hop from the proxy to CWNG stays HTTP. Kobo sync doesn't need WebSocket support. - Generate the token while visiting CWNG through the HTTPS address, so the
api_endpoint=line in the dialog already carries your public hostname. - If you stack proxies (for example Cloudflare Tunnel in front of nginx), set
TRUSTED_PROXY_COUNTto the number of proxies.
Kobo's /v1/library/sync response carries large headers (auth, sync tokens, library state), and nginx's default proxy_buffer_size (4 KB) and proxy_buffers (8 × 4 KB) are too small for them. nginx silently drops the response before it reaches the device: the Kobo shows "Sync failed, please try again", the CWNG log shows no error, and the nginx error log shows upstream sent too big header while reading response header from upstream. Add these to the location block that proxies CWNG, then reload nginx:
proxy_buffer_size 32k;
proxy_buffers 4 32k;
proxy_busy_buffers_size 64k;Larger libraries may need 128k, 4 256k and 256k. In Nginx Proxy Manager, add the three lines under the proxy host's Advanced tab. Synology DSM's reverse-proxy screen doesn't expose these directives: drop a custom config at /etc/nginx/conf.d/http.calibre_web.conf that mirrors the DSM entry plus the buffer lines, then disable the DSM entry. DSM rewrites nginx.conf on reboot, so add a Task Scheduler boot-up job that runs nginx -s reload to reapply the custom file. examples/nginx-reverse-proxy.conf is a complete reference.
Signing in to a Kobo account, or a factory reset, can rewrite the api_endpoint= line back to Kobo's own server, which sends sync to Kobo instead of your library. After signing in, re-check the line over USB and set it back if it changed. Many sideloaded setups stay signed out so the device stops resetting the endpoint.
To use the Kobo Store and your library at the same time, turn on Proxy unknown requests to Kobo Store in Admin → Edit Basic Configuration. With it off (the default), CWNG answers any request it doesn't recognize with an empty response. That's fine for a sideload-only device, but store features won't load. With it on, if the store refuses the calls a Kobo makes just before syncing, CWNG answers them empty, as it does with the setting off, and the log says Kobo Store refused .... Store features still need a signed-in Kobo.
The general cache defaults to cache/ under the app's config directory (/config/cache in Docker). Set CACHE_DIR to put it somewhere else; the service user must be able to write there. Thumbnails stay in /config/thumbnails, and metadata change logs and scratch storage keep their existing places under the config directory.
After an upgrade, disposable cache entries are regenerated in the new default location. The old cps/cache directory is left untouched, no user data or thumbnail cache is moved or deleted, and startup no longer creates or chowns that directory. Deployments that set CACHE_DIR keep their location.
Fixed in v4.0.13. If you still see it after upgrading, your book folders are probably owned by root:root from an older install. Run once:
docker exec calibre-web chown -R abc:abc /calibre-libraryFixed in v4.0.14. Upgrade the image.
Almost always one of these:
- The device isn't reaching your server. The
api_endpoint=line in.kobo/Kobo/Kobo eReader.confmust point at your CWNG address (notstoreapi.kobo.com), and that address must be reachable over HTTPS. See Kobo sync. - A Kobo account is signed in and Proxy unknown requests to Kobo Store is off, so the device's store calls get an empty response mid-sync. Turn that setting on, or sign out of the Kobo account on the device.
- Behind a reverse proxy, the proxy can't reach the container. Confirm the proxy target is
http://<host>:8083and the certificate is valid. - nginx is dropping the sync response because its default buffers are too small for Kobo's library-sync headers. The CWNG log shows the request arriving and nothing else; the nginx error log shows
upstream sent too big header. Raise the buffers as shown in nginx buffer sizes.
If your library is on a network share, set NETWORK_SHARE_MODE=true (see Network shares). On local disk this usually means the last container shutdown was unclean: restart Docker, then the container.
Set TRUSTED_PROXY_COUNT to match your proxy depth. See Reverse proxy / Cloudflare Tunnel.
- Files owned by root. Ingest files must belong to your
PUID:PGIDuser. - The watcher missed them. Click Refresh Library in the navbar for a one-off scan.
- The format isn't allowed. Check Admin → CWA Settings → Ingest for your allowed formats.
The defaults are admin / admin123, lowercase. If you changed the password and forgot it, stop the container, delete config/app.db and start it again. That resets the app database: user accounts are lost, and the library itself is untouched.
Search the issue tracker or open a new issue with:
- the version:
docker exec calibre-web printenv CWA_INSTALLED_VERSION - recent logs:
docker logs calibre-web 2>&1 | tail -50 - what you did and what you expected to happen
CWA v4.0.7 and v4.0.8 (September 2026) include many of the fixes that used to be listed here. Checked against CWA v4.0.8 in October 2026, these behaviors the two builds share still differ:
| Behavior | CWA v4.0.8 | This build |
|---|---|---|
| Docker healthcheck | Probes the web page at / |
Probes /health, which fails when the library database, the ingest service or the metadata-change service is down |
| Google Books covers | Requested at up to 800×900 | Requested at up to 1280×1920, for high-DPI e-readers such as the Kobo Libra Colour |
Features CWNG adds are in What's included. CHANGES-vs-upstream.md lists every change in this build, with its author and the release it shipped in. Backports are conservative: anything that touches auth, schema or dependencies gets a manual review before merging.
Completion refreshes automatically on every push to main, via scripts/generate_translation_status.py. To help translate, edit the .po file for your language under cps/translations/ and open a PR.
Completion by language
| Language | Completion | Strings | Fuzzy |
|---|---|---|---|
| English (source) | 100% | source | n/a |
French (fr) |
████████████████████ 100% |
4166/4169 | 0 |
Chinese (Simplified, China) (zh_Hans_CN) |
████████████████████ 99% |
4143/4169 | 0 |
German (de) |
████████████████████ 99% |
4145/4169 | 0 |
ca (ca) |
████████████████████ 98% |
4090/4169 | 0 |
Slovak (sk) |
████████████████████ 98% |
4085/4169 | 0 |
Russian (ru) |
████████████████████ 98% |
4075/4169 | 0 |
Swedish (sv) |
████████████████░░░░ 79% |
3298/4169 | 0 |
Dutch (nl) |
███████████████░░░░░ 77% |
3197/4169 | 279 |
Italian (it) |
███████████████░░░░░ 75% |
3109/4169 | 0 |
Spanish (es) |
███████████████░░░░░ 74% |
3093/4169 | 0 |
Chinese (Traditional, Taiwan) (zh_Hant_TW) |
█████████████░░░░░░░ 64% |
2672/4169 | 172 |
Polish (pl) |
████████████░░░░░░░░ 62% |
2574/4169 | 0 |
Hungarian (hu) |
████████░░░░░░░░░░░░ 42% |
1758/4169 | 118 |
Arabic (ar) |
███████░░░░░░░░░░░░░ 35% |
1464/4169 | 0 |
Portuguese (Brazil) (pt_BR) |
███████░░░░░░░░░░░░░ 34% |
1426/4169 | 296 |
Japanese (ja) |
██████░░░░░░░░░░░░░░ 32% |
1331/4169 | 234 |
Slovenian (sl) |
██████░░░░░░░░░░░░░░ 29% |
1226/4169 | 302 |
Korean (ko) |
█████░░░░░░░░░░░░░░░ 23% |
969/4169 | 256 |
Portuguese (pt) |
████░░░░░░░░░░░░░░░░ 22% |
899/4169 | 341 |
Indonesian (id) |
███░░░░░░░░░░░░░░░░░ 17% |
707/4169 | 343 |
Galician (gl) |
███░░░░░░░░░░░░░░░░░ 17% |
706/4169 | 342 |
Greek (el) |
███░░░░░░░░░░░░░░░░░ 13% |
538/4169 | 381 |
Czech (cs) |
██░░░░░░░░░░░░░░░░░░ 12% |
510/4169 | 390 |
Ukrainian (uk) |
██░░░░░░░░░░░░░░░░░░ 12% |
479/4169 | 357 |
Norwegian (no) |
██░░░░░░░░░░░░░░░░░░ 11% |
465/4169 | 417 |
Vietnamese (vi) |
██░░░░░░░░░░░░░░░░░░ 11% |
457/4169 | 338 |
Finnish (fi) |
██░░░░░░░░░░░░░░░░░░ 9% |
390/4169 | 371 |
Turkish (tr) |
██░░░░░░░░░░░░░░░░░░ 8% |
324/4169 | 369 |
Khmer (km) |
█░░░░░░░░░░░░░░░░░░░ 6% |
242/4169 | 330 |
- Bug reports: open a bug issue. Reproduction steps, the version tag and a
docker logssnippet help a lot. - Feature requests: open a feature issue. The bar is low, and you don't need to judge whether it's in scope. Bugs come first for code work; feature requests shape what gets picked up when the bug queue is quiet.
- Pull requests are welcome. The merge bar is "doesn't break anything that currently works", and changes touching auth, schema or dependencies get a closer review. Backports keep the original author's handle in the commit message.
- Have a PR open on CWA that you'd like shipped here too? Open an issue or send the PR over.
Governance: GOVERNANCE.md. Contribution details: CONTRIBUTING.md.
Since May 2026: 188 releases, 673 merged pull requests, 262 issues closed, and 155 contributors credited by name.
Nothing here is paywalled, and nothing ever will be: no sponsor-only features, no private Discord, no early access, no "pro" tier. Every line is GPL-3.0-or-later and free whether you contribute or not. Sponsorship keeps the work going.
If the project has been useful to you, a few dollars is a fair trade, and it's appreciated. If it hasn't, that's fine; it stays free either way.
- GitHub Sponsors: one-time or monthly. GitHub takes 0%, so all of it arrives.
- Ko-fi: the same, if you already have an account there.
The most useful thing you can do costs nothing: file a bug when something breaks.
The codebase itself is Calibre-Web and Calibre-Web-Automated, written over many years by their human maintainers and contributors, who are listed in Credits. What this fork adds on top (its own fixes, their regression tests, the changelog and most issue replies) is largely produced by an AI assistant working from a written brief, behind human review gates. A merge needs CI plus a regression test verified to fail without the fix, and a person decides anything that adds a dependency, changes a licence or introduces an external URL.
The application you run contains no AI: no model dependency, no inference call, no telemetry, and your library is not sent anywhere.
Built on:
- Calibre-Web-Automated by @crocodilestick and contributors, the software this build is based on.
- Calibre-Web by @janeczku and contributors, the web app underneath CWA.
- Calibre by @kovidgoyal, the library underneath all of it.
Every backported patch credits its original author by GitHub handle, in the commit message and in CHANGES-vs-upstream.md. To support the upstream project, @crocodilestick has a Ko-fi too.
License: GPL-3.0-or-later. See LICENSE.
