Skip to content

Plugins


Hatch utilizes pluggy for its plugin functionality.

Overview

All plugins provide registration hooks that return one or more classes that inherit from a particular type interface.

Each registration hook must be decorated by Hatch's hook marker. For example, if you wanted to create a new kind of environment you could do:

from hatchling.plugin import hookimpl

from .plugin import SpecialEnvironment


@hookimpl
def hatch_register_environment():
    return SpecialEnvironment

The hooks can return a single class or a list of classes.

Every class must define an attribute called PLUGIN_NAME that users will select when they wish to use the plugin. So in the example above, the class might be defined like:

...
class SpecialEnvironment(...):
    PLUGIN_NAME = 'special'
    ...

Project configuration

Naming

It is recommended that plugin project names are prefixed with hatch-. For example, if you wanted to make a plugin that provides some functionality for a product named foo you might do:

[project]
name = "hatch-foo"

Discovery

You'll need to define your project as a Python plugin for Hatch:

[project.entry-points.hatch]
foo = "pkg.hooks"

The name of the plugin should be the project name (excluding any hatch- prefix) and the path should represent the module that contains the registration hooks.

Classifier

Add Framework :: Hatch to your project's classifiers to make it easy to search for Hatch plugins:

[project]
classifiers = [
  ...
  "Framework :: Hatch",
  ...
]

Types

Hatchling

These are all involved in building projects and therefore any defined dependencies are automatically installed in each build environment.

Hatch

These must be installed in the same environment as Hatch itself.