{"id":267,"library":"pluggy","title":"pluggy","description":"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.","status":"active","version":"1.6.0","language":"python","source_language":"en","source_url":"https://github.com/pytest-dev/pluggy","tags":["plugin","hooks","pytest","extensibility","architecture"],"install":[{"cmd":"pip install pluggy","lang":"bash","label":"pip"},{"cmd":"uv add pluggy","lang":"bash","label":"uv"}],"dependencies":[],"imports":[{"note":"Also accessible as pluggy.HookspecMarker. Only top-level pluggy exports are public API.","symbol":"HookspecMarker","correct":"from pluggy import HookspecMarker"},{"note":"Also accessible as pluggy.HookimplMarker. Only top-level pluggy exports are public API.","symbol":"HookimplMarker","correct":"from pluggy import HookimplMarker"},{"note":"Internal submodules (pluggy.manager, pluggy.hooks, pluggy.callers) are private (prefixed with _). Import only from the top-level pluggy namespace.","wrong":"from pluggy.manager import PluginManager","symbol":"PluginManager","correct":"from pluggy import PluginManager"},{"note":"Raised when a hookimpl fails validation at registration time, e.g. hookwrapper=True on a non-generator function.","symbol":"PluginValidationError","correct":"from pluggy import PluginValidationError"},{"note":"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.","symbol":"Result","correct":"from pluggy import Result"}],"quickstart":{"code":"import pluggy\n\n# Both markers MUST share the same project name as PluginManager\nhookspec = pluggy.HookspecMarker(\"myproject\")\nhookimpl = pluggy.HookimplMarker(\"myproject\")\n\n\nclass MySpec:\n    \"\"\"Hook specification namespace.\"\"\"\n\n    @hookspec\n    def process(self, value: int) -> int:\n        \"\"\"Transform a value. Each implementation's return is collected into a list.\"\"\"\n\n\nclass PluginA:\n    @hookimpl\n    def process(self, value: int) -> int:\n        return value * 2\n\n\nclass PluginB:\n    @hookimpl(tryfirst=True)  # runs before PluginA despite LIFO default\n    def process(self, value: int) -> int:\n        return value + 10\n\n\npm = pluggy.PluginManager(\"myproject\")\npm.add_hookspecs(MySpec)       # register the spec BEFORE plugins\npm.register(PluginA())\npm.register(PluginB())\n\n# Hook calls MUST use keyword arguments only\nresults = pm.hook.process(value=5)\nprint(results)  # [15, 10]  — PluginB (tryfirst) then PluginA, LIFO order\n\n# New-style wrapper (>=1.2.0): use wrapper=True, plain function with yield\nclass WrapperPlugin:\n    @hookimpl(wrapper=True)\n    def process(self, value: int) -> int:\n        print(\"before\")\n        result = yield  # receives return value of inner calls\n        print(\"after\")\n        return result\n\npm.register(WrapperPlugin())\nresults2 = pm.hook.process(value=3)\nprint(results2)\n","lang":"python","description":"Define a hook spec and two implementations, register them with a PluginManager scoped to a project name, then call the hook and collect results."},"warnings":[{"fix":"Import all symbols exclusively from the top-level pluggy namespace: from pluggy import PluginManager, HookspecMarker, HookimplMarker, PluginValidationError, Result.","message":"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.","severity":"breaking","affected_versions":"<1.0.0 (made private in 1.0.0)"},{"fix":"Always pass hook arguments as keyword arguments: pm.hook.myhook(arg1=1, arg2=2).","message":"Hook calls must use keyword-only arguments. Calling pm.hook.myhook(1, 2) instead of pm.hook.myhook(arg1=1, arg2=2) raises TypeError.","severity":"breaking","affected_versions":"all"},{"fix":"Replace outcome.result with outcome.get_result(), which also re-raises any exception the hook raised.","message":"The _Result.result property was removed in 1.0.0. Code using outcome.result inside old-style hookwrappers will raise AttributeError.","severity":"breaking","affected_versions":"<1.0.0 (removed in 1.0.0)"},{"fix":"Upgrade to Python >=3.9 or pin pluggy<1.5 for Python 3.8 environments.","message":"Python 3.8 support was dropped in pluggy 1.5.0. Environments pinned to Python 3.8 must stay on pluggy <1.5.","severity":"breaking","affected_versions":">=1.5.0"},{"fix":"Migrate hookwrapper=True generator functions to wrapper=True. The yield in new-style wrappers receives the result value directly, not a Result object.","message":"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.","severity":"deprecated","affected_versions":">=1.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T12:38:07.111Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"pip install pluggy","cause":"The 'pluggy' package is not installed in the current Python environment or there's an issue with the Python path.","error":"ModuleNotFoundError: No module named 'pluggy'"},{"fix":"Ensure that all hook implementations have a matching hook specification defined using `pm.add_hookspecs(MySpecClass)` and that their function signatures (name and arguments) are compatible. If the hook is optional, mark the hook implementation with `@pluggy.hookimpl(optionalhook=True)`.","cause":"A hook implementation (hookimpl) is registered for a hook name that does not have a corresponding hook specification (hookspec) defined in the plugin manager, or the hookimpl's signature does not match the hookspec.","error":"pluggy.manager.PluginValidationError: unknown hook 'your_hook_name' in plugin 'your_plugin_name'"},{"fix":"Rewrite the hook wrapper function to be a generator that contains exactly one `yield` statement. For example:\n```python\n@hookimpl(wrapper=True)\ndef my_hook_wrapper(arg1, arg2):\n    print('before hook')\n    outcome = yield\n    print('after hook')\n    # Optionally process or force result/exception\n    # result = outcome.get_result()\n    # outcome.force_result(new_result)\n```","cause":"A hook implementation decorated with `wrapper=True` (new style) or `hookwrapper=True` (old style) is not implemented as a Python generator function (i.e., it's missing a `yield` statement).","error":"pluggy.manager.PluginValidationError: Plugin 'your_plugin_name' for hook 'your_hook_name'\\nhookimpl definition: ...\\nDeclared as wrapper=True or hookwrapper=True but function is not a generator function"},{"fix":"Upgrade your `pluggy` package to the latest version, or to a version compatible with the dependent library (e.g., `pytest`).\n`pip install --upgrade pluggy`","cause":"This error typically occurs when an older version of `pluggy` is used with a library (like `pytest`) that expects a newer `pluggy` feature or attribute that was introduced in a later version (e.g., pluggy>=1.4.0).","error":"AttributeError: module 'pluggy' has no attribute 'PluggyTeardownRaisedWarning'"},{"fix":"Reinstall `pluggy` to ensure all its components are correctly placed. It's also advisable to check your Python environment's site-packages for any conflicting files or directories named `pluggy` or `pluggy.py`.\n`pip uninstall pluggy`\n`pip install pluggy`","cause":"This usually indicates a corrupted installation, a conflict with another package that might shadow `pluggy`, or an attempt to import from an incorrect location. While `HookspecMarker` is a core `pluggy` component, this specific import error suggests the `pluggy` package itself might be misconfigured.","error":"ImportError: cannot import name 'HookspecMarker' from 'pluggy'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.5,"disk_size":"17.9M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.5,"disk_size":"18M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.7,"disk_size":"19.8M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.7,"disk_size":"20M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":1.6,"disk_size":"11.7M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":1.6,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2,"disk_size":"11.3M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.8,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.4,"disk_size":"17.4M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.4,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}