Skip to content


Chris Thurber edited this page May 4, 2022 · 28 revisions
Clone this wiki locally

Run-time Configuration Options

The configuration can be changed as admin in the admin panel under "Basic Configuration" and "UI Configuration"

Database Configuration:

Location of Calibre database:
The location of a valid metadata.db file as created by the Calibre program. The File has to be on a mounted drive of the server running Calibre-Web (for setup with Google Drive please take a look in the corresponding chapter). You only enter the path, no special care has to be taken about spaces or Non-ASCII characters. The must not be included in apostrophes. "/" or "" work as separators. The name metadata.db is not allowed as part of the path. The icon at the end of the input field can be used to conveniently select the desired file location. Example: /folder with space

With all installed G Drive dependencies a checkbox Use Google Drive? will show up. The further configuration steps for the G Drive integration are described here

Basic Configuration:

Server Configuration:

Server Port

Changes the port Calibre-Web is listening, changes take effect after pressing submit button. To reach the Calibre-Web instance afterwards you have to change the port manually in your browser, otherwise you see an endless "spinning wheel"

(Optional) SSL Configuration

For configuration of Calibre-Web as SSL Server go to the Config page in the Admin section. Enter the certfile- and keyfile-location, optionally change port to 443 and press submit. Afterwards the server can only be accessed via SSL. In case of a miss configuration (wrong/invalid files) both files can be overridden via command line options -c [certfile location] -k [keyfile location] By using "" as certfile/keyfile locations the server runs as non SSL server again. The correct file path can be entered on the config page afterwards. After the next restart without command line options the changed file paths are applied.

Update Channel

Calibre-Web provides 2 types of update. The Stable channel updates you less frequent from stable release to stable release. All releases are tested on a good base and are made for normal day use. The stable channel is the default setting.
The nightly mode includes new features latest bugfixes, and of course newest bugs. It's only recommended to use the nightly channel if you suffer from a certain bug fixed or if you want to be on the leading edge of technology.

Trusted Hosts

Enter additional trusted hosts as comma seperated list in this field. Additional hosts are needed for e.g. third party theming. Otherwise just lease the field empty

Logfile Configuration

Log Level

You can set the loglevel of the integrated logfiles. Default is INFO, which is recommended for normal day use. DEBUG gives you more information, especially during converting books and sending e-mails. WARNING and ERROR are less noisy as all other settings and create almost no entries. The logfiles are rotating automatically after 10kbytes of logged information are reached. The last 2versions are backuped.

Location and name of logfile

You can specify a different name and different location for the logfile. logfile.log creates a logfile with this name in the Calibre-Web config folder (root folder of Calibre-Web or the .calibre-web folder in your home directory), where c:\bücher\log.log creates a logfile with the name log.log in the "bücher" folder on drive "c:" (Windows). Please make sure Calibre-Web has write access to the folder you specify. You can use "/dev/stderr" to log to standard-error or "/dev/stdout" to log to the standard output. This magic pathes also work for windows installations

Enable Access Log

If activated Calibre-Web logs every request to the server in a seperate file (access.log per default). The path and name of the file can be changed with the same rules as mentioned in Location and name of Logfile

Feature Configuration

Convert non-English characters in title and author while saving to disk:

In the default behavior Calibre-Web converts all title and author names for saving to disk to their phonetic ASCII representation. To avoid this (especially for CJK-Languages) and keep the unicode chacacters uncheck this setting.

Enable Uploading:

Tick to enable uploading of PDF, kepub, epub, FB2, TXT, Mobi, AZW, AZW3, HTML, RTF, ODT, DJVU, PRC, DOC, DOCX, MP3, M4A, M4B, CBR, CBZ, and CBT files. The allowed file formats can be changed by editing the Allowed Upload Fileformats list. If imagemagick library is installed, covers can be extracted from some (PDF, epub, CBT, CBZ) of the uploaded file formats. With installed rarfile covers from cbr files can be extracted also. If a language viewing restriction is applied while uploading the book, book language is automatically set to this language to allow the user to view the recently uploaded book. Books can also be uploaded using drag and drop. Just drag your files to the main area of Calibre-Web, the shelf order page is excludes, all other pages work. Uploading more than one file at a time is also possible.

Enable anonymous browsing:

Tick to allow not logged-in users to browse the catalogue, anonymous user permissions can be changed as admin (showing up as "Guest" user in admin section)

Enable public registration:

Tick to enable public user registration. Users can then register with the Calibre-Web instance on their own with a valid email address. In the SMTP Server section valid domains for registrations can be limited. If the additional setting "Use E-Mail as Username" is set, users can not choose their own username, the e-mail address is taken as username. Prerequisites: The SMTP Server setup has to be completed.

Enable remote login ("magic link"):

Tick to enable remote login, i.e. a link that allows user to log in via a different device.

The remote login feature was made for devices where it is hard to enter a lot of text, like on ebook readers. After enabling this feature you see the magic link link on the login page:

On your ebook reader (or any other device you want to get logged in) you click on magic link. Afterwards you log in on you desktop computer with the account you want to get logged in on the reader and afterwards you enter the generated magic link (visible on your ebook reader) in the desktop computer. Magically after one or two seconds you are logged in on the ebook reader, too.

Enable Kobo sync

It's possible to sync your kobo reader with Calibre-Web. Configuration details are described here.

Allow Reverse Proxy Authentication

If you're using this feature, it's assumed that there's no access to the Calibre-Web service without going through the proxy responsible for setting the headers, as it allows for unchallenged login (i.e., it assumes the login challenge happens upstream, in some SSO flow). Don't use this setting for "normal" proxing applications.

External binaries

Path to Calibre E-Book Converter

You can choose to use calibre's ebook converter to convert ebooks from one format to another. In path to convertertool the path and name of the file ebook-converter (part of calibre) has to be entered. (On Linux usualy /opt/calibre/ebook-convert, for windows it's usually c:\program files\calibre\ebook-convert.exe). Calibre offers a lot of options to modify the behaviour of the ebook-converter, the options can be entered in the E-Book converter settings.
The filepicker icon right to the input field can be used to choose the right binary

Path to Kepubify E-Book Converter

You can choose to use the kepubify ebook converter to convert ebooks from epub to Kepub. The filepicker icon right to the input field can be used to choose the right binary.

Using Goodreads integration

This menu is only showing up if the optional dependencies "goodreads" and "python-Levenshtein" are installed. You need to have an API key with goodreads ( to use the feature. Currently, showing authors information are supported (view books by author).
Goodreads no longer allows to create new api tokens. The service will probably be discontinued sooner or later, so this feature will not be expanded.

Using LDAP for user handling

The configuration for LDAP login is described here.

UI Configuration:

View Configuration:


The title of the instance of Calibre-Web can be changed (useful if you are having more than on instance running). The name is shown in the upper left corner of the web page.

Books per page

Limits the number of book covers shown on one page (and the number of books loading during the infinite scrolling mode). To prevent the infinite scrolling mode set the "Books per page" to a number displayed on one page in your browser. In this case you will see pagination information on the bottom of the page (only valid for the Standard Theme)

No. of random books

Limits the number of books showing up in the random books section. To deactivate the feature untick the "Show random books in detail view" on the user's settings page.

No. of Authors to Display before hiding

If books having many authors, cover view pages can be very confusing. Therefore, it's possible to limit the number of authors shown in this case. Entering a zero deactivates this feature and all authors are shown.


Currently Calibre-Web supports two theme, the Standard light one, and the dark Caliblur! plex like theme.

Regular expression for ignoring columns and Link read/unread status to Calibre column

If you're having a Boolean custom column in Calibre you can use it as a "global" read/unread status (only useful in single user environments) In this case you can select this column in the Link read status. After saving the Read/Unread selection on each book is read from this column and also saved to this field in the calibre-database. Furthermore you should Enter this column name to the "Regular expression for ignoring columns", so the column isn't showing up twice in Calibre-Web.
Example: .\* would exclude all custom columns, Read only the column with the name column, ^My\scol.\* all Columns starting with My col. The filtering is based on the columns name (headline in German Calibre) and not the column lookup

Link Read/Unread Status to Calibre Column

For a Calibre-Web multi-user use case, please leave this field empty. In this case Calibre-Web stores the read status in it's own database. In a single user Calibre installation you can use a Boolean custom column to keep track of your read and unread books. Calibre-Web can do the following. You can link the Calibre status to the read/unread status in Calibre-Web. As mentioned above this only works in a SINGLE USER use-case. If you are having more than one user in Calibre-Web this will cause trouble, because the read/unread status is used for all users, so if one user ticks a book as read, all users will see this book as read. In a multi user Calibre-Web use case it's absolutely mandatory not to use this feature.
How to use the feature?

  1. Open Calibre (the Desktop program) and create a Boolean custom column name it accordingly (e.g. Read Status)
  2. Calibre will ask you for a restart to apply the change. Afterwards please close Calibre
  3. For safety reasons it's recommended to restart Calibre-Web
  4. Log in to Calibre-Web as admin and go to Admin->UI configuration->View Configuration
  5. The field "Link read/unread status to Calibre column" should now offer a selection of all Boolean custom columns of the corresponding Calibre library, select the appropriate entry and save The read/unread status is now identical in Calibre and Calibre-Web

Visibility Restrictions based on Calibre Custom Column

You can add restrictions based on Custom Columns if you want to hide certain books from some users (like your kids). In this setting you define the Custom Column where the restriction shall be based on. If you see None as only option, you have no text content Custom Columns in your Calibre Lib. The restrictions are on per user base, to change the restrictions of existing users, go to edit user and than you can edit the restrictions for this specific user.

Regular expression for title sorting

Calibre stores internally the title and a "sorted title". Title often starting with articles like "A" in English, or "Die/Der/Das" in German, which make no sense to sort after, therefore all of the listed words in these field are ignored for sorting the title. The default is taken from a German Calibre program. For french it should be something like "^(Le|La)\s"

Default settings and visibility for new users

The options selected in this section define the access rights and visibility new users having upon registering, and the default settings for newly created users by the admin (can be changed during initial creation, or later by admins). The visibility (except Visibility Restriction settings) can be changed by the users themselves later on. The Guest user (User for anonymous access) is an except from this, only admins can change the visibility for the Guest user.

Visibility Restrictions based on Calibre Custom Column

You can allow and deny the visibility of books based on the content of the Custom Column selected by View Restriction based on Calibre Custom Column setting. You can define a default Visibility in the Default Visibility for New Users section. Admins can change their own visibility restrictions on their own user settings page. Allowed column types are "Text, column shown in the Tag Browser" and "Comma separated text" You can restrict the visibility to only certain entries in this column (like user is only allowed to view books with entry "Kids") by allowing this Column entry, or exclude certain entries (like user is not allowed to view books with entry "Adult"). Allowing and denying content based on Custom Columns can be combined and can also be combined with restricts based on tags.

Visibility Restrictions based on Tags

You can allow and deny the visibility of books based on tags. You can define a default Visibility based on tags in the Default Visibility for New Users section. Admins can change their own visibility restrictions on their own user settings page. You can restrict the visibility to only certain tags (like user is only allowed to view books tagged as "kid") by allowing this tag, or exclude books with certain tags (like user is not allowed to view books with tag "Adult"). Allowing and denying content based on Custom Columns can be combined and can also be combined with restricts based on tags.

eBook Viewer and eBook Download

The integrated eBook viewer is available for pdf, epub, djvu, txt and cbr, cbz and cbt files. The option is showing up if user has the right to View Ebooks. If you are upgrading from older versions, it might be possible that the admin user lost the right to download or view books.