How to Configure Plugins

Functionality in Kupfer is organized by extentsion modules called "plugins". Each plugin provides additional functionality, for example integration with an external application.

Configuring Plugins

Open Kupfer Preferences to the Plugins tab

  1. Use one of the following methods:

    • Click the Kupfer icon in the notification area and select the item Preferences

    • Search for the object Kupfer Preferences in Kupfer itself. Press Return to open it.

    • Use the keyboard shortcut Ctrl+;

  2. Select the tab Plugins

Select plugins in the list to read about them, and tick the box next to its name to activate the plugin, or untick to deactivate.

If the plugin has any configurable parameters, they will be visible below the plugin information.

The plugin Kupfer Plugins allows fast access to each plugin's information page as well as the action "Show Source Code" which reveals the implementation.

If a Plugin can not be Activated

If a plugin fails to activate because it requires a software module that is not available, its plugin information will display a message like this:

Plugin could not be read due to an error:

Python module 'gdata' is needed

This means that you need to install a needed python module from your distribution—and possibly the plugin documentation can tell you how.

The plugin may also unexpectedly fail to load, and display a different error message. It may then be a program error in either the plugin or Kupfer.

Installing more Plugins

You can install custom plugins into the folder ~/.local/share/kupfer/plugins. Each plugin is either a single .py file or a python package (a folder directly containing a file called __init__.py). Plugins in the package format can include icon files. Python packages can even be installed as .zip files.

Caution: Treat a plugin as a computer program. Do not install untrusted plugins.

Creating Plugins

Documentation for plugin creators is available in the file Documentation/Manual.rst in the source distribution on the webpage at Kupfer Manual. An easy way to start is to copy an existing plugin and experimenting with it.

The Catalog Tab in Preferences

Each plugin can export a number of sources which contain objects. Normally, all these objects are directly accessible from a top-level search. Some plugins export so specialized or so many objects that their catalogs should better not have their objects exported to the top level. To reach those objects, you have to first find the catalog by name, then enter the catalog using the action Search Contents.

In the tab Catalog in Kupfer Preferences, a ticked box next to each source means that its objects are exported. An unticked box means that its contents are hidden from the top level.

Note: Kupfer may become slow if large enough subcatalogs are exported to the top level.