Introduction to plugins

[kiwidude]

What is a plugin?

Functionality in Calibre can be extended through the use of Python code snippets packaged as 'plugins'. The Calibre application itself comes with and makes extensive use of plugins developed by the Calibre development team, including for example:

• GUI features you see on your toolbars and right-click menus (User Interface Actions)
• Reading book metadata/covers from different websites (Metadata Source plugins)
• Conversion between book input/output formats (Conversion plugins)
• Connecting to different devices (Device Drivers)

Thanks to the Calibre plugins programming interface (API) it is equally possible for end-user developers to write their own plugins, that offer additional features they find useful or override the default Calibre behaviour. This sub-forum is dedicated to the user contributed plugins.

What plugins are available?

The most comprehensive list of plugins available is here in the MobileRead forums on the Index of plugins sticky thread. This same list is what you will see presented to you using Plugin Updater, discussed below.

In addition you can sometimes find beta versions of upcoming plugins in the Development subforum. These will need to be installed manually (see below).

You may find other Calibre plugins available on the internet using Google. Such plugins are not to be discussed in the MobileRead forums if they are for the purposes of removing DRM. Do not post asking in these forums how to install/use them or issues you have with them as this is against MobileRead policy.

How do I install a plugin using Plugin Updater?

As of Calibre 0.8.6, installing plugins from this sub-forum is easier than ever. Calibre now comes with something called "Plugin Updater", which prior to this release was itself a separate plugin.

1. Go to Preferences->Plugins and click on the Get new plugins button. Alternatively, click on the arrow next to the Preferences button on your toolbar and choose Get plugins to enhance calibre.
2. This screen will show you all of the plugins available from this forum. Right-click on a plugin to see more options, such as viewing more detailed information about the plugin in the forum thread in your web browser.
3. You may need to upgrade your version of Calibre to install some plugins as shown in the Calibre version column.
4. Select a plugin you would like to try, click the Install button, follow the prompts for each plugin
5. You may then be asked which toolbars/menus you would like the plugin to appear on if it is designed to have a user interface. Take care to put it on all you require, remember that there are different toolbars and menus for while your device is connected. You can always change your mind later using Preferences->Toolbar to change your selections.
6. Close the dialog when you are done.
7. You must restart calibre after installing plugins. A convenient shortcut for this is Ctrl+R.
8. Your plugin can often be customized by selecting it within the list in the Preferences->Plugins dialog, and clicking the Customize plugin button. You can also customize from the Plugin Updater dialog (after restarting). Some plugins have a menu which offers a Customize plugin shortcut as well.
9. Be sure to read the forum thread for your plugin to follow any additional instructions if required. For instance some plugins may require you to setup a custom column or perform some other steps for first usage.

How do I update my plugins?

For all of the plugins within this MobileRead subforum, Plugin Updater will notify you in a similar way to new Calibre versions being available with a hyperlink at the bottom of your screen. In addition if you have added the Plugin Updater icon to your toolbar, you will see the icon change to indicate one or more updates are available. Click on either the link or the icon, select the plugin to upgrade and click the Install button as per the instructions above.

You can also check for updates manually if you have the Plugin Updater icon on your toolbar, or from Preferences->Plugins clicking on the Check for updated plugins button.


How do I install a plugin manually?

You will need to manually install a plugin if you:

• Want to install a beta version of a plugin listed on a forum thread
• Want to install a plugin you downloaded somewhere else off the internet
• Are developing your own plugin

To install a plugin using the Calibre gui:

1. Download the plugin zip file, taking care that it is not unzipped or touched by any antivirus or download managers you use.
2. In Calibre choose Preferences->Plugins. Click the Load plugin from file button (Calibre 0.8.6 or later) or Add new plugin button (Calibre 0.8.5 or earlier) to browse to your plugin .zip file and click OK.
3. You may then be asked which toolbars/menus you would like the plugin to appear on if it is designed to have a user interface. Take care to put it on all you require, remember that there are different toolbars and menus for while your device is connected. You can always change your mind later using Preferences->Toolbar to change your selections.
4. Restart Calibre after installing a plugin. Ctrl+R is a convenient shortcut for this.
5. As discussed above, your plugin may need further customisation using Customize plugin from Preferences->Plugins or the Plugin Updater dialog.

To install a plugin using the command line:

1. Download the plugin zip file, taking care that it is not unzipped or touched by any antivirus or download managers you use.
2. Close Calibre if it is currently running.
3. From a command prompt, type calibre-customize -a "My Plugin Name.zip"
4. Start Calibre and go to Preferences->Toolbar if you want to add it to a toolbar or menu for the first time.

What if the plugin doesn't work?

1. Any questions/issues concerning functionality of these plugins should be kept in the relevant thread in this forum. Do not use the Calibre bug tracker, support is within this forum from the plugin developers and other users.
2. Before you post, double check you have followed all the install instructions specified above and any in the plugin post itself.
3. You can obtain the plugin error details by starting Calibre in debug mode. You can do this from the Preferences menu-> Restart in debug mode or from a command window using calibre-debug -g. Be sure to include the full error output with your post.
4. If the plugin is stopping calibre from starting, you can try starting it with the command line of calibre --ignore-plugins
   This will prevent any custom plugins from attempting to be loaded. Then go to the Preferences->Plugins dialog and disable or uninstall the plugin which is causing a problem until the developer is able to provide a fix or workaround.

How do I write my own plugin?

Writing a plugin offers a great way to contribute to the Calibre community. In addition to simply looking at the code within the plugins available on this forum, you should find the following links useful:

• Calibre Manual - Creating Plugins
• Calibre Manual - Plugin API
• Calibre Manual - Setting up a Development Environment