pluggy

1.6.0 · active · verified Sat Mar 28

pluggy is the crystallized core of plugin management and hook calling for pytest, powering 1400+ pytest plugins and pytest itself. It provides HookspecMarker and HookimplMarker decorators to define typed hook contracts, a PluginManager to register plugins and dispatch calls, and supports hook ordering (tryfirst/trylast), firstresult short-circuiting, historic hooks, and new-style generator-based hook wrappers. Current stable version is 1.6.0 (released May 15, 2025); releases follow Semantic Versioning with breaking changes reserved for major version bumps.

Warnings

breaking Internal submodules pluggy.callers, pluggy.manager, and pluggy.hooks are private. Importing from them (e.g. from pluggy.manager import PluginManager) will break across any release.
Fix: Import all symbols exclusively from the top-level pluggy namespace: from pluggy import PluginManager, HookspecMarker, HookimplMarker, PluginValidationError, Result.
breaking Hook calls must use keyword-only arguments. Calling pm.hook.myhook(1, 2) instead of pm.hook.myhook(arg1=1, arg2=2) raises TypeError.
Fix: Always pass hook arguments as keyword arguments: pm.hook.myhook(arg1=1, arg2=2).
breaking The _Result.result property was removed in 1.0.0. Code using outcome.result inside old-style hookwrappers will raise AttributeError.
Fix: Replace outcome.result with outcome.get_result(), which also re-raises any exception the hook raised.
breaking Python 3.8 support was dropped in pluggy 1.5.0. Environments pinned to Python 3.8 must stay on pluggy <1.5.
Fix: Upgrade to Python >=3.9 or pin pluggy<1.5 for Python 3.8 environments.
deprecated Old-style hook wrappers (hookwrapper=True) are soft-deprecated in favor of new-style wrappers (wrapper=True, added in 1.2.0). Old-style wrappers now emit PluggyTeardownRaisedWarning when an exception is raised during teardown.
Fix: Migrate hookwrapper=True generator functions to wrapper=True. The yield in new-style wrappers receives the result value directly, not a Result object.
gotcha Multiple hook implementations are called in Last In First Out (LIFO) order by default: the last-registered plugin runs first. Return values are collected into a list in that same order.
Fix: Use @hookimpl(tryfirst=True) or @hookimpl(trylast=True) to explicitly control execution order, or @hookspec(firstresult=True) on the spec to stop after the first non-None result.
gotcha HookspecMarker, HookimplMarker, and PluginManager must all be initialized with the SAME project_name string. A mismatch silently causes implementations to be ignored — no error is raised.
Fix: Define the project_name as a module-level constant (e.g. PROJECT_NAME = 'myproject') and reference it in all three places to prevent typo-driven silent failures.

Install

pip install pluggy pip
uv add pluggy uv

Imports

HookspecMarker
```
from pluggy import HookspecMarker
```
Also accessible as pluggy.HookspecMarker. Only top-level pluggy exports are public API.
HookimplMarker
```
from pluggy import HookimplMarker
```
Also accessible as pluggy.HookimplMarker. Only top-level pluggy exports are public API.
PluginManager
```
from pluggy import PluginManager
```
Internal submodules (pluggy.manager, pluggy.hooks, pluggy.callers) are private (prefixed with _). Import only from the top-level pluggy namespace.
PluginValidationError
```
from pluggy import PluginValidationError
```
Raised when a hookimpl fails validation at registration time, e.g. hookwrapper=True on a non-generator function.
Result
```
from pluggy import Result
```
Used inside old-style hookwrappers (hookwrapper=True). The deprecated .result property was removed in 1.0.0; always call .get_result() which re-raises on failure.

Quickstart

Define a hook spec and two implementations, register them with a PluginManager scoped to a project name, then call the hook and collect results.

import pluggy

# Both markers MUST share the same project name as PluginManager
hookspec = pluggy.HookspecMarker("myproject")
hookimpl = pluggy.HookimplMarker("myproject")


class MySpec:
    """Hook specification namespace."""

    @hookspec
    def process(self, value: int) -> int:
        """Transform a value. Each implementation's return is collected into a list."""


class PluginA:
    @hookimpl
    def process(self, value: int) -> int:
        return value * 2


class PluginB:
    @hookimpl(tryfirst=True)  # runs before PluginA despite LIFO default
    def process(self, value: int) -> int:
        return value + 10


pm = pluggy.PluginManager("myproject")
pm.add_hookspecs(MySpec)       # register the spec BEFORE plugins
pm.register(PluginA())
pm.register(PluginB())

# Hook calls MUST use keyword arguments only
results = pm.hook.process(value=5)
print(results)  # [15, 10]  — PluginB (tryfirst) then PluginA, LIFO order

# New-style wrapper (>=1.2.0): use wrapper=True, plain function with yield
class WrapperPlugin:
    @hookimpl(wrapper=True)
    def process(self, value: int) -> int:
        print("before")
        result = yield  # receives return value of inner calls
        print("after")
        return result

pm.register(WrapperPlugin())
results2 = pm.hook.process(value=3)
print(results2)

view raw JSON →