Skip to content
Rohitt Vashishtha edited this page Feb 27, 2024 · 43 revisions

What to do with problems during installation with error message "Import-Error"?

Python is a very modular programming language, special functionality can be included to the program by "importing modules". If one of this modules isn't found you get the error message 'ImportError: No module named xxxx'. This shouldn't be happen, you normally can solve this by installing the missing module with pip[3] --target vendor install [module-name]. Pip3 is normally used if you are using python 3.x - depending on the distro it could also be named pip.

What do I do if I lose my "Admin" password?

If there is more than on admin on your instance, any other admin can generate a new password for your account. Otherwise, stop your Calibre-Web instance and start Calibre-Web with the commandline option -s [username]:[newpassword], to set a new password for your admin

How to Backup Calibre-Web Settings?

All settings of Calibre-Web are stored in the app.db in the root folder of the project. If you are using Google Drive as ebook storage than you also need to backup the gdrive.db, settings.yaml and gdrive_credentials files.

Which OPDS-Readers work with Calibre-Web?

I have successfully tested the following OPDS-Readers:

  • Chunky on iOS (mainly for comics)
  • Marvin and Marvin3 on iOS (no longer available in App Store)
  • Calibre-Companion on Android (Book downloads viewing book details are also supported with this reader even it's not using the standard opds features). Download is only working with anonymous browsing enabled
  • Kybook 1/2/3 on iOS
  • Megareader on iOS (download seems not to work)
  • moon+ on Android (Cover pictures are only displayed with anonymous browsing enabled, tested with v4.5.7)
  • ebookdroid on Android (Download is only working with anonymous browsing enabled with v2.6.3)
  • Coolreader on Android (Cover pictures are not supported, tested with v3.2.29-1)
  • FBReader on Android (Cover pictures are only displayed with anonymous browsing enabled, tested with v3.0.8)
  • Librera Reader on Android (Catalogue browsing and downloading works, with cover pictures, tested v8.9.158-fdroid)
  • Koreader on Kobo, Kindle, Android, Desktop OSes and other platforms has a compatible OPDS browser.
  • Foliate on Linux (Cover pictures are not supported)

I'm not using all the readers regularly, so issues might appear from time to time. If it's reported I'll try to fix it.

If there is no space to provide your credentials (e.g. in Moon+ Reader) you can add them to the catalogue link (you will need to urlencode any special characters):

https://calibre-web.example.com/opds?auth=username:password

or

https://username:[email protected]/opds

Download File / Cover not found problems

Why is my epub xxx.epub not working in the reader? Calibre-Web uses the futurepress-javascript-epub-reader library to display epubs. Unfortunately some ebooks aren't fully specification compliant, and the epub-reader library has it's own limitations and errors, so from time to time certain ebook aren't displayable by Calibre-Web.

Why don't you support Calibre's virtual Libs?

Virtual libraries are implemented as searches in Calibre's own searching language. Supporting this would mean a complete reimplementation of Calibre's searching functions, which is a bit out of my time and Calibre-Web's feature scope.

What is the maximum file-size which can be uploaded through Calibre-Web?

Calibre-Web's default server ('tornado') limits the uploaded file size to 200MB, 'Gevent' the server from the optional requirement has no hardcoded limit (or nothing I'm aware of).

My file is smaller then 200MB, but I get a '413 - Request Entity To Large' error message

If you are using some additional systems like a proxy or reverse proxy, they must be configured to support the file size as well. See https://www.keycdn.com/support/413-request-entity-too-large for a possible fix.

Can Calibre-Web execute malicious code in an epub?

If you just organize your epubs with Calibre-Web, the content of the epub is not touched, and nothing gets to execution.
If you use the included epub-reader, it is a different story:
Calibre-Web unpacks the epub (which are normal zip files) to a folder on the server which is accessible by the browser. Then Calibre-Web sends the reader page to the browser. The browser starts the epub-reader JavaScript file, which itself starts to build up the webpage you see. During that process, the file contents of the epub file are loaded into the browser. The content is just normal html pages, which can include stylesheet files and JavaScript files. So if there is malicious code included the epub, or links to JavaScript code, the browser (if not prevented somehow) will start to interpret it.

If you are not sure, you could rename the epub to zip open it and search for js-code and delete it, and afterwards rename it to epub again. Also tools like the Sigil Epub Editor could help to dig deeper into the suspicious books.

What to do if cover pictures are not extracted from PDF files:

Symptom: Calibre-Web logs a message like: WARNING - PDF extraction forbidden by ImageMagick policy: not authorized '/tmp/calibre_web/xxxxxxxxxxxxxxxxxx' @ error/constitute.c/ReadImage/412 during upload of PDF files. ImageMagick recently changed their security policy, they now deny per default PDF operations, so covers can't be extracted anymore, you have to allow it in the policy.xml file of ImageMagick (located in /etc/Imagemagick-6) by changing line: <policy domain="coder" rights="none" pattern="PDF" /> to <policy domain="coder" rights="read" pattern="PDF" />

Calibre-Web has to be restarted after changing the policy.xml file. Covers should be extracted without error from uploaded PDF files.

Mass add books

It's possible to upload several books at once by selecting more than one file. The limitation is the upload size of the Calibre-Web internal server (several hundred megabyte). Another possibility is via a normal shall script by watching a folder content. Prerequisites for the example below is an installed Calibre program. The script has to be called regularly (cron job). The script watches for content in the supervised path, calls Calibre to add the files in the folder to the library and deletes the files in the last step from the source folder.

#!/bin/bash
if [ "$(ls -A [folder to watch] )" ]; then
     calibredb add -r "[folder to watch]" --library-path="[path to calibre library]"
     rm [folder to watch]/*
fi

Login Kobo

Kobo readers having problems using the internal web browser on non-standard ports. This means with the Calibre-Web standard port the magic login link normally doesn't work. As workaround Calibre-Web could be accessed via reverse proxy, or using the normal login method.

Non ASCII Filenames on disk

Non ASCII Filenames, including author names (containing korean, chinese, ... characters) are changed to a transliterated representation. In newer versions ticking the setting "Convert non-English characters in title and author while saving to disk" will save the books with their original characters

Invalid SSL configuration

In case you entered invalid key files for accessing Calibre-Web through https, the ssl configuration can be overridden using the commandline arguments "-c" and "-k". The file locations can than be corrected in the web-UI.

Arrange and fill Shelves

Shelves can be filled book by book on the corresponding detail page. Books can also be mass added from the result of an advanced search. The third option for adding many books at one time to a shelf is using a script like the cps-mass-adder script. The order of books in a shelf can be rearranged on the shelf edit page via drag 'n drop.

Send to kindle with guest account

In a one-user use case you can use the guest account for sending ebooks to kindle. In this case please add a kindle-email to the guest account; afterwards the "send to kindle" button appears for the guest user. If more than one user is accessing the guest account this will not work, as you can only have one kindle-email linked to a user.

Link Read Status to Calibre Custom Column

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 have 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 multiuser 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

How to handle Multiple Calibre Libraries

The recommended way for handling multiple libraries is to start multiple instances of Calibre-Web. Instead of having several copies of the Calibre-Web code, command line options can be used for this. First start Calibre-Web with the normal command:
python3 [path to calibre-web]/cps.py
Configure the path to the metadata.db, set the logfile to a new filename (e.g. instance1.log) and change the port to e.g. 8084. Now stop Calibre-Web rename the newly generated app.db to e.g. instance1.db. Repeat this procedure for every instance you want to run. At the end start all instance with the commandline-parameter -p:

nohup python3 [path to calibre-web]cps.py -p /[path to calibre-web instance1.db]
nohup python3 [path to calibre-web]cps.py -p /[path to calibre-web instance2.db]
...
nohup python3 [path to calibre-web]cps.py -p /[path to calibre-web instanceN.db]

The command nohup puts the command to the background, so all instances can be started at once. Another option would be using several terminal windows. The final solution would be creating different service files for the different instances. All instances will be accessible afterwards with different port addresses like:
127.0.0.1:8084 for instance1, 127.0.0.1:8085 for instance2 and so on. This procedure can also be used for Windows with the usual adoptions (command console/batch program instead of terminal, task planer instead of service script).

Concurrent access (Calibre and Calibre-Web)

If Calibre is started first, it normally blocks access to the metadata.db file and it's not possible to start Calibre-Web afterwards. If Calibre-Web is started first it's possible to access the metadata.db file via Calibre later. If Calibre and Calibre-Web are changing book-metadata at the same time this can lead to unpredictable result.

How to upload Covers in other formats than jpg?

Other cover formats than jpg can be uploaded using the "upload from local drive" function on the edit book page. If "pillow" is installed, other file formats like png can be converted to jpg and used as cover.

How many books are displayed on Random/Discover section

The random books page is generated new upon each call to the page (also valid for the opds feed). The random page therefore has no next page and the number of books displayed there is equal to the setting books per page

Which picture formats are supported in the comic reader?

The comic reader supports currently jpg, jpeg, png, gif (but not animated ones) and svg.

Which types of Custom columns are supported?

All types of custom columns are supported except the two "Columns Build from other Columns". From the "Long text, like comments..." column only the HTML formatted version is supported.