Packaging Plugins

stoQ has a built-in plugin installation and upgrade capability. stoQ plugins may be packaged to allow for a simple and consistent installation process. Though packaging plugins isn’t a necessity, it is highly recommended to do so for simplicity and reproducibility.

Let’s take a look at a basic directory structure for a stoQ plugin:

|-- example_plugin/
|   `--
|   `--
|   `-- requirements.txt
|   `-- example_plugin/
|       `--
|       `--
|       `-- example_plugin.stoq

stoQ plugin packages leverage python’s packaging library, setuptools. When a plugin is installed, pip is used for package management and installation. As such, all rules for both apply for stoQ plugins.

The file is a standard setuptools script. include_package_data should always be set to True to ensure the plugin configuration file and any additional files are properly installed.

from setuptools import setup, find_packages
    author="Marcus LaFerrera (@mlaferrera)",
    license="Apache License 2.0",
    description="Example stoQ plugin",

The manifest file ensure that the plugins .stoq configuration file, and any other required files, are installed alongside the plugin. More information on the .stoq configuration file can be found here.

include example_plugin/*.stoq


If a requirements file exists, stoQ will install dependencies appropriately. They will not be installed along side the plugin, but rather in python’s system path. This file is not required if no additional dependencies need to be installed.

plugin subdirectory

The subdirectory above, example_plugin, is the primary plugin directory. This is the core location for the stoQ plugin that will be installed into the stoQ plugin directory. The plugin module, along with files identified in will be copied.

More information on writing a plugin can be found here.


There are plenty of examples for packaging plugin in stoQ’s public plugin repository.