| 1 |
.. currentmodule:: calibre.customize.__init__ |
| 2 |
|
| 3 |
.. _customize: |
| 4 |
|
| 5 |
Customizing calibre |
| 6 |
================================== |
| 7 |
|
| 8 |
calibre has a highly modular design. Various parts of it can be customized. Here, you will learn: |
| 9 |
|
| 10 |
* how to use environment variables and *tweaks* to customize calibre's behavior, |
| 11 |
* how to specify your own static resources like icons and templates to override the defaults |
| 12 |
* how to use *plugins* to add functionality to calibre. |
| 13 |
* how to share icon themes and plugins with other calibre users. |
| 14 |
* to see how to create *recipes* to add new sources of online content to calibre visit the Section :ref:`news`. |
| 15 |
|
| 16 |
.. note:: |
| 17 |
Note that although icon themes and plugins are indexed and downloadable |
| 18 |
via calibre's builtin updater, they are not part of calibre, and their |
| 19 |
canonical locations for support and source code are on the `Mobileread forums |
| 20 |
<https://www.mobileread.com/forums/forumdisplay.php?f=166>`__ in their support |
| 21 |
threads. |
| 22 |
|
| 23 |
.. contents:: |
| 24 |
:depth: 2 |
| 25 |
:local: |
| 26 |
|
| 27 |
.. toctree:: |
| 28 |
:hidden: |
| 29 |
|
| 30 |
plugins |
| 31 |
|
| 32 |
|
| 33 |
.. _customize_env_vars: |
| 34 |
|
| 35 |
Environment variables |
| 36 |
----------------------- |
| 37 |
|
| 38 |
* ``CALIBRE_CONFIG_DIRECTORY`` - sets the folder where configuration files are stored/read. |
| 39 |
* ``CALIBRE_TEMP_DIR`` - sets the temporary folder used by calibre |
| 40 |
* ``CALIBRE_CACHE_DIRECTORY`` - sets the folder calibre uses to cache persistent data between sessions |
| 41 |
* ``CALIBRE_OVERRIDE_DATABASE_PATH`` - allows you to specify the full path to metadata.db. Using this variable you can have metadata.db be in a location other than the library folder. Useful if your library folder is on a networked drive that does not support file locking. |
| 42 |
* ``CALIBRE_ALLOW_PYTHON_TEMPLATES`` - if set to a value other than ``1`` disables the use of Python based templates in calibre. |
| 43 |
* ``CALIBRE_DEVELOP_FROM`` - used to run from a calibre development environment. See :ref:`develop`. |
| 44 |
* ``CALIBRE_OVERRIDE_LANG`` - used to force the language used by the interface (ISO 639 language code) |
| 45 |
* ``CALIBRE_TEST_TRANSLATION`` - used to test a translation .po file (should be the path to the .po file) |
| 46 |
* ``CALIBRE_NO_NATIVE_FILEDIALOGS`` - causes calibre to not use native file dialogs for selecting files/folders. |
| 47 |
* ``CALIBRE_NO_NATIVE_MENUBAR`` - causes calibre to not create a native (global) menu on Ubuntu Unity and similar Linux desktop environments. The menu is instead placed inside the window, as is traditional. |
| 48 |
* ``CALIBRE_USE_SYSTEM_THEME`` - by default, on Linux, calibre uses its own |
| 49 |
builtin Qt style. This is to avoid crashes and hangs caused by incompatibilities |
| 50 |
between the version of Qt calibre is built against and the system Qt. The |
| 51 |
downside is that calibre may not follow the system look and feel. If |
| 52 |
you set this environment variable on Linux, it will cause calibre to use |
| 53 |
the system theme -- beware of crashes and hangs. |
| 54 |
* ``CALIBRE_SHOW_DEPRECATION_WARNINGS`` - causes calibre to print deprecation warnings to stdout. Useful for calibre developers. |
| 55 |
* ``CALIBRE_NO_DEFAULT_PROGRAMS`` - prevent calibre from automatically registering the filetypes it is capable of handling with Windows. |
| 56 |
* ``CALIBRE_USE_SYSTEM_CERTIFICATES`` - make calibre use the system certificate store for SSL certificate verification instead of its own certificate store on Windows and macOS. |
| 57 |
* ``CALIBRE_NO_ICONS_IN_MENUS`` - Disable icons in menus |
| 58 |
* ``QT_QPA_PLATFORM`` - On Linux set this to ``wayland`` to force calibre to use Wayland and ``xcb`` to force use of X11. |
| 59 |
* ``SYSFS_PATH`` - Use if sysfs is mounted somewhere other than /sys |
| 60 |
* ``http_proxy``, ``https_proxy`` - used on Linux to specify an HTTP(S) proxy |
| 61 |
|
| 62 |
See `How to set environment variables in Windows <https://www.computerhope.com/issues/ch000549.htm>`_. If you are on macOS |
| 63 |
you can set environment variables by creating the :file:`~/Library/Preferences/calibre/macos-env.txt` and putting |
| 64 |
the environment variables one per line in it, for example:: |
| 65 |
|
| 66 |
CALIBRE_DEVELOP_FROM=$HOME/calibre-src/src |
| 67 |
CALIBRE_NO_NATIVE_FILEDIALOGS=1 |
| 68 |
CALIBRE_CONFIG_DIRECTORY=~/.config/calibre |
| 69 |
|
| 70 |
|
| 71 |
Tweaks |
| 72 |
------------ |
| 73 |
|
| 74 |
Tweaks are small changes that you can specify to control various aspects of calibre's behavior. You can change them by going to Preferences->Advanced->Tweaks. |
| 75 |
The default values for the tweaks are reproduced below |
| 76 |
|
| 77 |
.. literalinclude:: ../resources/default_tweaks.py |
| 78 |
|
| 79 |
|
| 80 |
Overriding icons, templates, et cetera |
| 81 |
---------------------------------------- |
| 82 |
|
| 83 |
.. note:: |
| 84 |
calibre has direct support for icon themes, there are several icon themes |
| 85 |
available for calibre, that you can use by going to :guilabel:`Preferences->Interface->Look & Feel->Change icon theme`. |
| 86 |
It is preferable to use icon themes over overriding individual icons. |
| 87 |
|
| 88 |
|
| 89 |
calibre allows you to override the static resources, like icons, JavaScript and |
| 90 |
templates for the metadata jacket, catalogs, etc. with customized versions that |
| 91 |
you like. All static resources are stored in the resources sub-folder of the |
| 92 |
calibre install location. On Windows, this is usually :file:`C:\\Program Files\\Calibre2\\app\\resources`. |
| 93 |
On macOS, :file:`/Applications/calibre.app/Contents/Resources/resources/`. On Linux, if |
| 94 |
you are using the binary installer from the calibre website it will be |
| 95 |
:file:`/opt/calibre/resources`. These paths can change depending on where you |
| 96 |
choose to install calibre. |
| 97 |
|
| 98 |
You should not change the files in this resources folder, as your changes will |
| 99 |
get overwritten the next time you update calibre. Instead, go to |
| 100 |
:guilabel:`Preferences->Advanced->Miscellaneous` and click |
| 101 |
:guilabel:`Open calibre configuration folder`. In this configuration folder, create a |
| 102 |
sub-folder called resources and place the files you want to override in it. |
| 103 |
Place the files in the appropriate sub folders, for example place images in |
| 104 |
:file:`resources/images`, etc. calibre will automatically use your custom file |
| 105 |
in preference to the built-in one the next time it is started. |
| 106 |
|
| 107 |
For example, if you wanted to change the icon for the :guilabel:`Remove books` |
| 108 |
action, you would first look in the built-in resources folder and see that the |
| 109 |
relevant file is :file:`resources/images/remove_books.png`. Assuming you have an |
| 110 |
alternate icon in PNG format called :file:`my_remove_books.png` you would save it in |
| 111 |
the configuration folder as :file:`resources/images/remove_books.png`. All the |
| 112 |
icons used by the calibre user interface are in :file:`resources/images` and |
| 113 |
its sub-folders. Placing an override file here will have even higher priority |
| 114 |
than a custom icon theme. |
| 115 |
|
| 116 |
Creating your own icon theme for calibre |
| 117 |
------------------------------------------------------------- |
| 118 |
|
| 119 |
If you have created a beautiful set of icons and wish to share them with other |
| 120 |
calibre users via calibre's builtin icon theme support, you can easily package |
| 121 |
up your icons into a theme. To do so, go to |
| 122 |
:guilabel:`Preferences->Miscellaneous->Create icon theme`, select the folder |
| 123 |
where you have put your icons. Then fill in the theme |
| 124 |
metadata and click OK. This will result in a ZIP file containing the theme |
| 125 |
icons. You can upload that to the calibre forum at `Mobileread |
| 126 |
<https://www.mobileread.com/forums/forumdisplay.php?f=166>`__ and then I will |
| 127 |
make your theme available via calibre's builtin icon theme system. |
| 128 |
By default, the icon theme you just created will also be installed as the |
| 129 |
current theme in calibre. If you are testing your theme, remember to remove |
| 130 |
the images from the :file:`resources/images` folder so that the icons from the |
| 131 |
theme are used. |
| 132 |
|
| 133 |
As of calibre 6, you can have custom icons for light and dark mode. Simply |
| 134 |
create two versions of the icon and name the files with the suffix |
| 135 |
``-for-dark-theme`` and ``-for-light-theme``. For example, |
| 136 |
``modified-for-dark-theme.png`` and ``modified-for-light-theme.png``. Then |
| 137 |
calibre will automatically use the appropriate icon based on the current theme. |
| 138 |
|
| 139 |
Customizing calibre with plugins |
| 140 |
-------------------------------- |
| 141 |
|
| 142 |
calibre has a very modular design. Almost all functionality in calibre comes in |
| 143 |
the form of plugins. Plugins are used for conversion, for downloading news |
| 144 |
(though these are called recipes), for various components of the user |
| 145 |
interface, to connect to different devices, to process files when adding them |
| 146 |
to calibre and so on. You can get a complete list of all the built-in plugins |
| 147 |
in calibre by going to :guilabel:`Preferences->Advanced->Plugins`. |
| 148 |
|
| 149 |
You can write your own plugins to customize and extend the behavior of calibre. |
| 150 |
The plugin architecture in calibre is very simple, see the tutorial |
| 151 |
:ref:`pluginstutorial`. |
| 152 |
|
| 153 |
Once you have written a plugin, you can upload that to the calibre plugins |
| 154 |
forum at `Mobileread |
| 155 |
<https://www.mobileread.com/forums/forumdisplay.php?f=237>`__ and it will be |
| 156 |
made available via calibre's builtin plugin updater. |