Control Properties

As already mentioned earlier, plugins are Python packages which provide certain pieces of metadata to tell OctoPrint’s plugin subsystem about themselves. These are simple package attributes defined in the top most package file, e.g.:

import octoprint.plugin

# ...

__plugin_name__ = "My Plugin"
__plugin_pythoncompat__ = ">=2.7,<4"
def __plugin_load__():
    # whatever you need to do to load your plugin, if anything at all

The following properties are recognized:


Name of your plugin, optional, overrides the name specified in if provided. If neither this property nor a name from is available to the plugin subsystem, the plugin’s identifier (= package name) will be used instead.


Version of your plugin, optional, overrides the version specified in if provided.


Description of your plugin, optional, overrides the description specified in if provided.


Author of your plugin, optional, overrides the author specified in if provided.


URL of the webpage of your plugin, e.g. the Github repository, optional, overrides the URL specified in if provided.


License of your plugin, optional, overrides the license specified in if provided.


Python compatibility string of your plugin, optional, defaults to >=2.7,<3 if not set and thus Python 2 but no Python 3 compatibility.

If your plugin is compatible to Python 3, you should set this to >=2.7,<4, otherwise your plugin will not load on OctoPrint instances installed under Python 3.

__plugin_pythoncompat__ = ">=2.7,<4"

Instance of an implementation of one or more plugin mixins. E.g.

__plugin_implementation__ = MyPlugin()

Handlers for one or more of the various plugin hooks. E.g.

def handle_gcode_sent(comm_instance, phase, cmd, cmd_type, gcode, *args, **kwargs):
    if gcode in ("M106", "M107"):
        import logging
        logging.getLogger(__name__).info("We just sent a fan command to the printer!")

__plugin_hooks__ = {
    "octoprint.comm.protocol.gcode.sent": handle_gcode_sent

Method called upon discovery of the plugin by the plugin subsystem, should return True if the plugin can be instantiated later on, False if there are reasons why not, e.g. if dependencies are missing. An example:

def __plugin_check__():
    # Make sure we only run our plugin if some_dependency is available
        import some_dependency
    except ImportError:
        return False

    return True

Method called upon loading of the plugin by the plugin subsystem, can be used to instantiate plugin implementations, connecting them to hooks etc. An example:

def __plugin_load__():
    global __plugin_implementation__
    __plugin_implementation__ = MyPlugin()

    global __plugin_hooks__
    __plugin_hooks__ = {
        "octoprint.plugin.softwareupdate.check_config": __plugin_implementation__.get_update_information

Method called upon unloading of the plugin by the plugin subsystem, can be used to do any final clean ups.


Method called upon enabling of the plugin by the plugin subsystem. Also see on_plugin_enabled().


Method called upon disabling of the plugin by the plugin subsystem. Also see on_plugin_disabled().


An optional dict providing an overlay over the application’s default settings. Plugins can use that to modify the default settings of OctoPrint and its plugins that apply when there’s no different configuration present in config.yaml. Note that config.yaml has the final say - it is not possible to override what is in there through an overlay. Plugin authors should use this sparingly - it’s supposed to be utilized when creating specific customization of the core application that necessitate changes in things like e.g. standard naming, UI ordering or API endpoints. Example:

__plugin_settings_overlay__ = dict(api=dict(enabled=False),