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

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

Symptoms

QuickBox Pro v3 installed and configured
User account created on the server
eBook collection ready to organize and manage
Supported distro: Debian 11/12/13 or Ubuntu 22.04/24.04

Resolution

Use QuickBox's qb command for installation
Automatic Python venv setup per user using the distro's system Python
Dual installation: Calibre-Web + Calibre Content Server
Customizable library path with -lp / --library-path flag

Basic Installation

Install Calibre for a specific user:


qb install calibre -u username

Advanced Installation with Custom Library Path


qb install calibre -u username --library-path '/mnt/storage/ebooks'

CLI Commands

Command	Description
`qb install calibre -u username`	Install Calibre with default library path
`qb install calibre -u username -lp '/path/to/library'`	Install with custom eBook library location
`qb reinstall calibre -u username`	Reinstall Calibre (preserves library and configuration)
`qb update calibre -u username`	Update Calibre-Web to latest GitHub release
`qb remove calibre -u username`	Remove Calibre and clean up files
`qb help calibre`	Display comprehensive help information

CLI Options

-u usernameRequired

Target user for the Calibre installation

qb install calibre -u john

-lp '/path'

Custom library path for eBook storage. Alias: --library-path

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

Automatic Port Assignment

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

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

Column 1	Column 2	Column 3
Debian 11	bullseye	Python 3.9
Ubuntu 22.04	jammy	Python 3.10
Debian 12	bookworm	Python 3.11
Ubuntu 24.04	noble	Python 3.12
Debian 13	trixie	Python 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

Calibre is automatically integrated into your QuickBox dashboard. Find it in the Service Control panel with port and status information. Click the LAUNCH icon to open Calibre-Web.

Default Credentials (Calibre-Web):

Username: Your QuickBox username
Password: Your QuickBox password

Calibre Content Server Access

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:

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

2. Add eBooks to Library

Upload and organize your eBooks:

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

3. Configure Reading Options

Customize the reading experience:

Go to Admin → Basic Configuration
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)
Set default language and timezone
Configure email server for eBook delivery (optional)
Save configuration

Configuration and Files

Calibre paths and files

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/

│ │ └── calibre.log# v3 CLI installer log

└── 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.


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.


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

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


systemctl restart calibreweb@username calibreserver@username
systemctl reload nginx

Troubleshooting

Calibre-Web Won’t Start


journalctl -u calibreweb@username -f

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


# 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


# 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


# 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


# 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


# 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

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

Use Cases

Personal eBook Library

Organize thousands of eBooks with automatic metadata and cover art
Read eBooks directly in browser with built-in web reader
Convert between formats for different eReader devices
Send eBooks to Kindle via email (configured SMTP)

Multi-Device Reading

Sync library to Kindle, Kobo, Nook, and other eReaders
Access library from mobile devices via OPDS catalog
Download eBooks for offline reading on tablets and phones
Track reading progress across multiple devices

eBook Collection Management

Bulk metadata editing for large library imports
Series management with automatic ordering
Tag-based organization and filtering
Custom columns for tracking read status, location, and personal ratings

FAQ

Calibre-Web (calibreweb@username) is a modern Python-based web interface for browsing, reading, and managing your eBook library. Calibre Content Server (calibreserver@username) is the native Calibre binary server that provides OPDS catalog support and direct device sync. Both share the same library but run as independent services.

QuickBox uses your distro's system Python version: Python 3.9 on Debian 11, Python 3.10 on Ubuntu 22.04, Python 3.11 on Debian 12, Python 3.12 on Ubuntu 24.04, and Python 3.13 on Debian 13. The version is selected automatically during installation.

You can update the library path in the app.db database: sqlite3 /home/username/.config/Calibre/web/app.db "UPDATE settings SET config_calibre_dir='/new/path' WHERE id='1';". Then restart the service: systemctl restart calibreweb@username. Alternatively, reinstall with a new path: qb reinstall calibre -u username -lp '/new/path'.

Calibre-Web starts at base port 8500 and Calibre Content Server at base port 9500. Ports are auto-incremented per user, so the second user would get 8501 and 9501. Both services are reverse-proxied through nginx, so users access them via https://domain/username/calibre and https://domain/username/calibre-server/.

v4 dashboard operation logs are stored at /opt/v4-dashboard/var/log/username/package-{action}-{jobId}.log where {action} is install, remove, or update. The v3 CLI installer log is at /opt/quickbox/logs/calibre.log.

Yes. The -lp (or --library-path) flag works with both qb install and qb reinstall. For example: qb reinstall calibre -u username -lp '/new/library/path'.

📚

Book Management

LazyLibrarian Readarr

📖

Comic/Manga Readers

Kavita Komga

🎬

Media Servers

Plex Jellyfin

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

Calibre

📚 Universal Format Support

🌐 Dual Web Interface

✏️ eBook Editing

🔄 Format Conversion

📱 eReader Sync

🔍 Metadata Management

🐍 Per-Distro Python Venv

📋 Install Logging

Installation

Symptoms

Resolution

Basic Installation

Advanced Installation with Custom Library Path

CLI Commands

CLI Options

Accessing Calibre

Initial Configuration

1. Set Up eBook Library

2. Add eBooks to Library

3. Configure Reading Options

Configuration and Files

Service Management

Calibre-Web (calibreweb@username)

Calibre Content Server (calibreserver@username)

Restart Both Services

Troubleshooting

Calibre-Web Won’t Start

Library Not Loading

Symptoms

Resolution

eBook Upload Fails

Format Conversion Not Working

Cannot Login After Password Change

Calibre Content Server Not Accessible

Debian 13 (Trixie) Compatibility

Python Version Mismatch

Symptoms

Resolution

Best Practices

Do

Don't

Use Cases

Personal eBook Library

Multi-Device Reading

eBook Collection Management

FAQ

Related Applications

Book Management

Comic/Manga Readers

Media Servers

Additional Resources

Join the Community

Calibre-Web (`calibreweb@username`)

Calibre Content Server (`calibreserver@username`)