Skip to Content
ApplicationsE-Books & ComicsCalibre
Calibre

Calibre

Complete eBook library management and conversion suite

Calibre is a cross-platform open-source suite of eBook software that supports organizing existing eBooks into virtual libraries, displaying, editing, creating, and converting eBooks, as well as syncing with a variety of eReaders. QuickBox Pro installs both Calibre-Web (modern web interface) and Calibre Content Server (native content server) with a per-user Python virtual environment, systemd services, auto-incremented ports, and customizable library paths for comprehensive eBook management.

Universal Format Support

Read, convert, and manage EPUB, MOBI, AZW3, PDF, and 30+ eBook formats

Dual Web Interface

Calibre-Web (calibreweb service) for modern UI and Calibre Content Server (calibreserver service) for device sync and OPDS

eBook Editing

Built-in editor for EPUB and AZW3 formats with table of contents and metadata

Format Conversion

Convert between any eBook format with customizable conversion settings

eReader Sync

Direct sync to Kindle, Kobo, Nook, and other eReaders via USB or wireless

Metadata Management

Automatic metadata fetching from multiple sources with cover art download

Per-Distro Python Venv

Calibre-Web runs in an isolated Python virtual environment using your distro's system Python version — fully managed by QuickBox

Install Logging

Full install, update, and remove logs via the v3 CLI and v4 dashboard operation logs for troubleshooting

Dual-Service Architecture
Note

QuickBox Pro installs two independent services per user: Calibre-Web (calibreweb@username, base port 8500) for modern web access and Calibre Content Server (calibreserver@username, base port 9500) for device sync and OPDS catalog support. Each service can be managed independently.

Installation

Install from the Dashboard

Open App Dashboard → Package Management (/dashboard?mode=packages), find Calibre in the E-Books & Comics category (or search), and click Install. The install dialog includes a Library Path field — set where Calibre stores its library, or leave the default (/home/username/.config/Calibre/library). The dashboard streams the install log live, and both Calibre services appear in your Application Control panel when it finishes. Reinstall, Update, and Remove are on the same panel.

What you see is gated by your account: admins manage any user’s apps, regular users manage their own. See App Management for the full flow.

Install from the CLI (automation)

The CLI runs the same scripts and suits automation. The Library Path dialog field maps to the -lp / --library-path flag:

bash
qb install calibre -u username                                   # default library path
qb install calibre -u username -lp '/path/to/library'            # custom library (short flag)
qb install calibre -u username --library-path '/mnt/storage/ebooks'  # custom library (long flag)
qb reinstall calibre -u username -lp '/new/library/path'         # reinstall, preserves library
qb update calibre -u username                                    # update Calibre-Web
qb remove calibre -u username                                    # remove and clean up
qb help calibre                                                  # show usage and options

CLI Options

OptionDescriptionExample
-u, --usernameRequired

Target user for the Calibre installation

qb install calibre -u john
qb install calibre -u john
-lp, --library-path

Custom library path for eBook storage

qb install calibre -u john -lp '/mnt/storage/ebooks'
qb install calibre -u john -lp '/mnt/storage/ebooks'

Full flag reference: CLI Reference.

Automatic Port Assignment
Tip

QuickBox automatically assigns dual ports per user:

  • Calibre-Web: Starting at 8500 (auto-incremented per user)
  • Calibre Content Server: Starting at 9500 (auto-incremented per user)

Actual ports depend on how many users have Calibre installed. Find your assigned ports in the QuickBox dashboard.

Python Virtual Environment
Info

Calibre-Web runs in an isolated Python virtual environment at /opt/username/Calibre/.venv. QuickBox automatically uses the correct Python version for your distro:

DistributionCodenamePython Version
Debian 11bullseyePython 3.9
Ubuntu 22.04jammyPython 3.10
Debian 12bookwormPython 3.11
Ubuntu 24.04noblePython 3.12
Debian 13trixiePython 3.13

Accessing Calibre

After installation, access Calibre components:

Calibre-Web (Primary Interface):

https://your-server-ip/username/calibre

Calibre Content Server (Device Sync):

https://your-server-ip/username/calibre-server
QuickBox Dashboard Integration
Tip

Calibre is automatically integrated into your QuickBox dashboard. Find it on the App Dashboard (the default control view), expand its row for port and status, and click Open to open Calibre-Web.

Default Credentials (Calibre-Web):

  • Username: Your QuickBox username
  • Password: Your QuickBox password
Calibre Content Server Access
Info

The Calibre Content Server uses digest authentication with credentials set during installation (matching your QuickBox username and password). The nginx reverse proxy also requires basic authentication via your server’s htpasswd file. Both the calibreweb and calibreserver services must be running for full functionality.

Initial Configuration

1. Set Up eBook Library

On first access to Calibre-Web:

  1. Login with your QuickBox credentials
  2. Library path is pre-configured:
    • Default: /home/username/.config/Calibre/library
    • Custom: Your specified --library-path during install
  3. Click Submit to complete setup
  4. Library loads with sample metadata database

2. Add eBooks to Library

Upload and organize your eBooks:

  1. Navigate to Upload Book (top menu)
  2. Click Choose Files and select eBooks
  3. Supported formats:
    • EPUB - Most common, best compatibility
    • MOBI/AZW3 - Kindle formats
    • PDF - Documents and scanned books
    • CBZ/CBR - Comics and manga
  4. Click Upload to add to library
  5. Edit metadata:
    • Title, author, publisher
    • Series and series index
    • Tags and categories
    • Cover art upload

3. Configure Reading Options

Customize the reading experience:

  1. Go to Admin → Basic Configuration
  2. Configure features:
    • Enable uploads - Allow book uploads
    • Enable eBook conversion - Format conversion support
    • Enable eBook viewer - Built-in web reader
    • Enable public registration - Allow user sign-ups (optional)
  3. Set default language and timezone
  4. Configure email server for eBook delivery (optional)
  5. Save configuration

Configuration and Files

Calibre paths and files
Path
Description
/
opt/
username/
Calibre/
Application install directory
.venv/
Python virtual environment (distro-specific version)
calibre/
Native Calibre binaries (calibre-server, calibredb, ebook-convert)
web/
Calibre-Web application (cloned from GitHub)
quickbox/
logs/
software
v3 CLI install log (shared by all app installs)
v4-dashboard/
var/log/username/
v4 dashboard operation logs
package-install-{jobId}.log
Dashboard install operation log
package-remove-{jobId}.log
Dashboard remove operation log
package-update-{jobId}.log
Dashboard update operation log
home/
username/
.config/
Calibre/
User configuration directory
library/
Default eBook library (or custom -lp path)
web/
Calibre-Web configuration
app.db
Calibre-Web settings and user database
server.log
Calibre Content Server log
tmp/
Calibre/
Temporary upload directory
etc/
nginx/
software/
username.calibre.conf
Calibre-Web nginx reverse proxy
username.calibre-server.conf
Calibre Content Server nginx reverse proxy
systemd/
system/
calibreweb@username.service
Calibre-Web systemd service
calibreserver@username.service
Calibre Content Server systemd service

Service Management

Calibre runs two independent per-user systemd services. Each can be managed separately:

Calibre-Web (calibreweb@username)

The primary web interface — a Python Flask application serving the modern library UI.

bash
systemctl status calibreweb@username     # Check status
systemctl restart calibreweb@username    # Restart service
systemctl stop calibreweb@username       # Stop service
journalctl -u calibreweb@username -f     # View live logs

Calibre Content Server (calibreserver@username)

The native Calibre content server — provides OPDS catalog, device sync, and direct library access.

bash
systemctl status calibreserver@username  # Check status
systemctl restart calibreserver@username # Restart service
systemctl stop calibreserver@username    # Stop service
journalctl -u calibreserver@username -f  # View live logs
Service Independence
Tip

The two services are independent. You can restart calibreweb without affecting calibreserver and vice versa. If you only need the web UI, calibreweb is sufficient. If you need OPDS catalog access for mobile apps or eReader sync, ensure calibreserver is also running.

Restart Both Services

bash
systemctl restart calibreweb@username calibreserver@username
systemctl reload nginx

Troubleshooting

Calibre-Web Won’t Start

bash
journalctl -u calibreweb@username -f

Check the Python venv. The Python version depends on your distro (see the Python version table above):

bash
# List available Python binaries in the venv
ls -la /opt/username/Calibre/.venv/bin/python*
 
# Verify the venv Python works
/opt/username/Calibre/.venv/bin/python3 --version
 
# If the venv is broken, reinstall:
qb reinstall calibre -u username

Library Not Loading

Symptoms

  • Calibre-Web shows 'DB Location is not Valid' error
  • Library path cannot be found
  • Books not appearing in library
  • Metadata database errors

Resolution

  • Verify library path: ls -la /home/username/.config/Calibre/library
  • Check metadata.db exists in library directory
  • Verify permissions: chown username:username -R /path/to/library
  • Check app.db config: sqlite3 ~/.config/Calibre/web/app.db 'SELECT config_calibre_dir FROM settings;'
  • Restart Calibre-Web: systemctl restart calibreweb@username

eBook Upload Fails

bash
# Check upload directory permissions
ls -la /home/username/tmp/Calibre
 
# Verify disk space
df -h
 
# Check allowed upload size
# Admin → Basic Configuration → Upload
 
# Check logs for specific errors
journalctl -u calibreweb@username -f | grep -i upload

Format Conversion Not Working

bash
# Verify Calibre binaries are installed
ls -la /opt/username/Calibre/calibre/
 
# Check conversion settings
# Admin → Basic Configuration → External Binaries
 
# Test conversion manually
/opt/username/Calibre/calibre/ebook-convert --version
 
# Enable conversion in Calibre-Web
# Admin → Feature Configuration → Enable eBook Converter

Cannot Login After Password Change

bash
# Stop Calibre-Web
systemctl stop calibreweb@username
 
# Reset admin user password via sqlite
sqlite3 /home/username/.config/Calibre/web/app.db "UPDATE user SET password='<new-hash>' WHERE name='username';"
 
# Or reinstall (preserves library):
qb reinstall calibre -u username

Calibre Content Server Not Accessible

bash
# Verify service is running
systemctl status calibreserver@username
 
# Check nginx reverse proxy
sudo nginx -t
sudo systemctl reload nginx
 
# Test direct port access (use your actual assigned port)
curl -I http://localhost:9500
 
# Check service logs
journalctl -u calibreserver@username -f

Debian 13 (Trixie) Compatibility

Debian 13 — libgl1-mesa-glx
Info

On Debian 13 (trixie), the libgl1-mesa-glx package is no longer available in the repositories. QuickBox handles this automatically during installation by using the appropriate replacement packages. No manual intervention is required.

Python Version Mismatch

If you upgrade your distro (e.g., Debian 11 to Debian 12), the system Python version changes and the existing venv may break.

Symptoms

  • Calibre-Web fails to start after a distro upgrade
  • Python binary not found in /opt/username/Calibre/.venv/bin/
  • ModuleNotFoundError or ImportError in calibreweb journal logs

Resolution

  • Reinstall Calibre to rebuild the venv with the new Python version: qb reinstall calibre -u username
  • The reinstall preserves your library data and configuration
  • Verify the new venv: ls -la /opt/username/Calibre/.venv/bin/python*

Best Practices

Do

  • Organize eBooks with proper metadata (title, author, series, tags)
  • Use EPUB format when possible for best compatibility and features
  • Enable automatic metadata fetching for cover art and book information
  • Create collections and tags to organize large libraries effectively
  • Regularly backup your library directory (default: /home/username/.config/Calibre/library)
  • Use custom columns for additional book metadata (read status, location, rating)
  • Enable eBook conversion for format flexibility across devices
  • Set up OPDS catalog for mobile app access via Calibre Content Server (calibreserver)

Don't

  • Don't delete /home/username/.config/Calibre/ — contains library database and web config
  • Don't manually edit metadata.db while Calibre services are running
  • Don't upload DRM-protected eBooks — Calibre cannot manage them
  • Don't use special characters in book filenames that break file systems
  • Don't share admin credentials — create separate user accounts instead
  • Don't ignore library backups — database corruption can lose all metadata
  • Don't store library on the same partition as OS without sufficient space
  • Don't convert formats unnecessarily — original format is often best quality

FAQ

Book Management

1
LazyLibrarian

Comic/Manga Readers

2
KavitaKomga

Media Servers

2
PlexJellyfin

Additional Resources

Calibre Official Website

Official homepage and downloads

Calibre-Web GitHub

Web interface source code and issues

Calibre Manual

Comprehensive user manual

Calibre Forums

Community support and discussions

Join the Community

Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.

  • Dedicated Support
  • Feature Previews
  • Community Configs
  • Active Discussions
Join Discord Server
Last updated on
E-Books & ComicsKavita