Calibre-Web Automated (formerly Calibre-Web Automator)

Making Calibre-Web your dream, all-in-one self-hosted digital library solution.

Supporting the Project ❤️

CWA is and always will be free and open source. If it makes your library life easier and you're able to support development, contributions go directly to: - Testing hardware (ereader devices & tablets ect.) - Development tools and infrastructure - Coffee ☕ (lots of coffee)

Quick Access

• Features 🪄
• Releases 🆕
• Roadmap 🛣️
• How to Install: 📖
• Quick Install 🚀
• Docker-Compose 🐋⭐(Recommended)
• Users Migrating from stock Calibre Web 🔄
• Post-Install Tasks 🏁
  • Default Login Credentials 🔑
• Usage 🔧
• Adding Books to Your Library
• KOReader Syncing (KOSync) 📖⚡
• OAuth Authentication Setup 🔐
• For Developers 🚀
• Further Development 🏗️

Why does it exist? 🔓

Calibre, while a fantastic tool for its age, has several problems when containerised, including its reliance on a KasmVNC server instance for the UI, which is near impossible to use on mobile and is relatively resource-heavy if you're running a small, lower power server like I am.

For many, Calibre-Web has really swooped in to save the day, offering an alternative to a containerised Calibre instance that's resource-light and with a much more modern UI to boot.

However, when compared to full-fat Calibre, it unfortunately lacks a few core features leading many to run both services in parallel, each serving to fill in where the other lacks, resulting in an often clunky, imperfect solution.

Goal of the Project 🎯

Calibre-Web Automated aims to be an all-in-one solution, combining the modern lightweight web UI from Calibre-Web with the robust, versatile feature set of Calibre, with a slew of extra features and automations thrown in on top.

CWA allows you to keep your ebook library accessible & organised and looks good while doing it 😎🦚

Affiliated Projects 👬

Shelfmark: Book Downloader

• An intuitive web interface for searching and requesting book downloads, designed to work seamlessly with Calibre-Web-Automated. This project streamlines the process of downloading books and preparing them for integration into your Calibre library

[!IMPORTANT]
CWA does not approve of or support piracy of copyrighted materials and is not responsible for user behaviour

---

Calibre-Web Companion

• Built with Flutter and using Material You, Calibre Web Companion is an unofficial companion application for Calibre Web & Calibre Web Automated that allows you to browse your book collection and download books directly on your device, providing a much more modern, mobile-friendly UX than either service can currently provide on its own

Join our Community! ❤️

• I want to say a big thanks 🙏 to all the members of this community that have taken the time to participate in the testing and development of this project and we encourage anyone who would like to to contribute in some way. Anyone of any level is welcome and every little helps!

• For anyone that wish to contribute to this project in some way, please reach out on our Discord Server and see how you can best get involved:\ \

• Or alternatively make your own companion project, come hang out and or come get help if you're facing issues :)

🚨 Deploying on Network Shares (NFS/SMB) 🚨

• CWA now supports network-share deployments via NETWORK_SHARE_MODE=true
• This disables SQLite WAL on metadata.db and app.db to prevent locking issues
• Skips recursive ownership changes that often fail on NFS/SMB
• Switches ingest/metadata watchers to a polling-based watcher for reliability
• Network shares are still slower than local disks, but are now fully supported with this mode enabled

Network shares and SQLite WAL mode

• CWA optimizes SQLite concurrency by enabling Write-Ahead Logging (WAL) on local disks.
• Some network filesystems (NFS/SMB) do not fully support WAL or reliable file locking, which can cause intermittent "database is locked" errors or corruption risks.

• If you are deploying on a network share, set the following environment variable to disable WAL:

• NETWORK_SHARE_MODE=true

This tells CWA to avoid enabling WAL on the Calibre metadata.db and the app.db settings database. It also disables recursive ownership changes (chown) performed by init/maintenance scripts to avoid permission issues on network filesystems. Default is false (WAL enabled) for better performance on local disks.

File watching on network shares

• By default, CWA uses Linux inotify (via inotifywait) to detect new files in the ingest folder with minimal latency and overhead.
• On network shares (NFS/SMB), filesystem events can be unreliable or unavailable. When NETWORK_SHARE_MODE=true is set, CWA switches the ingest and metadata watcher services to a polling-based watcher that periodically scans for changes. This improves reliability on NAS/network mounts at the cost of slightly higher I/O and up to a few seconds of latency.
• On Docker Desktop (Windows/macOS), the container runs on a LinuxKit/WSL2 VM and host-mounted paths may not propagate inotify events reliably. CWA auto-detects Docker Desktop at startup and prefers the same polling watcher for reliability.
• Advanced: You can also force polling regardless of share mode by setting CWA_WATCH_MODE=poll.

Running behind multiple proxies (Cloudflare Tunnel, reverse proxy)

• CWA uses Werkzeug's ProxyFix middleware to properly handle X-Forwarded-For, X-Forwarded-Proto, and other proxy headers.

• By default, it trusts 1 proxy in the chain. If you have multiple proxies (e.g., Cloudflare Tunnel → nginx → CWA), set:

• TRUSTED_PROXY_COUNT=2 (or the total number of proxies in your chain)

• Why this matters: Session protection validates requests based on the client's IP address. If ProxyFix doesn't trust enough proxies, it may see different IPs between requests, causing "Session protection triggered" warnings and forcing re-login.

• Troubleshooting: If you see frequent session protection warnings in logs, check your proxy chain depth and adjust this variable accordingly.

Features:

CWA supports all Stock CW Features:

Modern & responsive Bootstrap 3 HTML5 interface	Comprehensive user management with per-user permissions	OPDS feed for ereader apps
eBook metadata editing and deletion support	Metadata download from various sources (extensible via plugins)	eBook download restriction to logged-in users
Public user registration support	Send eBooks to E-Readers with a single click	Sync Kobo devices with your Calibre library
In-browser eBook reading support for multiple formats	Content hiding based on categories and Custom Column content per user	"Magic Link" login for easy access on eReaders
Enhanced OAuth 2.0/OIDC authentication with auto-discovery	Advanced search and filtering options	Multilingual user interface supporting 20+ languages

Plus these CWA Specific Features on top:

Click a feature below to read about it in more detail:

Automatic Ingest Service ✨	Automatic Conversion Service 🔃	Automatic Enforcement of Covers & Metadata 👀📔
Batch Editing & Deletion 🗂️	Automated Back Up Service 🔒	Automated Setup Experience for New Users 🦮
Automatic EPUB Fixer Service 🔨	Multi-Format Conversion Service 🌌	Library Auto-Detect 📚🕵️
Smart Duplicate Detection & Management 🔍	Magic Shelves 🪄📚	Auto-Send to eReader 📧⚡
Automatic Metadata Fetch on Ingest 🏷️🤖	Deep Stats & Analytics 📊✨	Easy Dark/ Light Mode Switching ☀️🌙
Internal Update Notification System 🛎️	Auto-Compression of Backed Up Files 🤐	Additional Metadata Providers 🗃️
KOReader Syncing (KOSync) 📖⚡	Enhanced OAuth 2.0/OIDC Authentication 🔐	EPUB Fixer 2.0 📧✅
Automatic Hardcover ID Fetch 💜🤖	Server Stats Tracking Page 📍	Enhanced Send-to-eReader Modal ✉️

Automatic Ingest Service ✨

• CWA currently supports automatic ingest of 27 different popular ebook formats
• Users can configure the services behavior to ignore and/or have certain formats automatically converted to other formats in the Admin Panel

Automatic Conversion Service 🔃

• On by default though can be toggled off in the CWA Settings page, with EPUB as the default target format
• Available target formats include: EPUB, MOBI, AZW3, KEPUB & PDF
• Upon detecting new files in the Ingest Directory, if any of the files are in formats the user has configured CWA to auto-convert to the current target format,
• The following 28 file types are currently supported:
• .acsm, .azw, .azw3, .azw4, .mobi, .cbz, .cbr, .cb7, .cbc, .chm, .djvu, .docx, .epub, .fb2, .fbz, .html, .htmlz, .lit, .lrf, .odt, .pdf, .prc, .pdb, .pml, .rb, .rtf, .snb, .tcr, .txtz
• Note: .acsm requires an additional Calibre plugin

Automatic Enforcement of Changes made to Covers & Metadata through the Calibre-Web UI! 👀📔

• In stock Calibre-Web, any changes made to a book's Cover and/or Metadata are only applied to how the book appears in the Calibre-Web UI, changing nothing in the ebook's files like you would expect
• This results in a frustrating situation for many CW users who utilise CW's Send-To-Kindle function, and are disappointed to find that the High-Quality Covers they picked out and carefully chosen Metadata they sourced are completely absent on all their other devices! UGH!
• CWA's Automatic Cover & Metadata Enforcement Feature makes it so that WHATEVER you changes you make to YOUR books, are made to the books themselves, as well as in the Web UI, making what you see, what you get.

Automated Back Up Service 🔒

• Worried what will happen if something goes wrong during one of CWA's automated functions? Don't be!
• By default, the originals all files processed by CWA are stored in /config/processed_books though this can be toggled in the CWA Settings panel

Smart Duplicate Detection System & Management 🔍

• Hybrid SQL + fuzzy matching detects duplicates missed by traditional scans
• Post-ingest checks and scheduled incremental scans
• One-click merge, batch operations, and optional auto-resolution
• Configurable matching rules, thresholds, and format awareness

Magic Shelves 🪄📚

• Dynamic, rules-based shelv