pyproject-hooks

1.2.0 verified Tue May 12 auth: no python install: verified quickstart: stale

A low-level library for calling build-backends in pyproject.toml-based Python projects. Current version: 1.2.0, released on September 29, 2024. Maintained by Thomas Kluyver, it provides basic functionality to help write tooling that generates distribution files from Python projects. If you want a tool that builds Python packages, you'll want to use https://github.com/pypa/build instead. This is an underlying piece for pip, build, and other 'build frontends' use to call 'build backends' within them. Note: The pep517 project has been replaced by this project (low level) and the build project (high level).

pip install pyproject-hooks

Common errors

error ImportError: cannot import name 'build_wheel' from 'pyproject_hooks' ↓

cause Developers often mistake `pyproject-hooks` as a high-level build tool and attempt to import functions like `build_wheel` directly, which are methods of the `BackendHookCaller` class, not top-level functions.

fix

Use a high-level build frontend like build (e.g., python -m build) for building packages. If you need to interact with build hooks at a low level, instantiate pyproject_hooks.BackendHookCaller and call its methods.

error ModuleNotFoundError: No module named 'pyproject_hooks' ↓

cause The `pyproject-hooks` package is not installed in the current Python environment. It's often an indirect dependency for build tools like `pip` or `build`, so direct installation might be overlooked if a developer tries to use its API explicitly.

fix

Install the package using pip: pip install pyproject-hooks

error ModuleNotFoundError: No module named 'setuptools.build_meta' ↓

cause When `pyproject-hooks` attempts to load the specified build backend (e.g., `setuptools.build_meta` or `flit_core.build_api`) from the `pyproject.toml` file or an explicitly passed `build_backend` argument, the module cannot be found. This usually means the build backend package itself is not installed, or its name is misspelled in `pyproject.toml`.

fix

Ensure the build backend specified in your pyproject.toml (e.g., build-system.requires and build-system.build-backend) is installed in your environment. For setuptools.build_meta, install setuptools: pip install setuptools. For flit_core.build_api, install flit-core: pip install flit-core.

error TypeError: BackendHookCaller.__init__ missing 1 required positional argument: 'build_backend' ↓

cause The `pyproject_hooks.BackendHookCaller` class requires the `build_backend` argument during instantiation, specifying the Python import path to the build backend (e.g., 'setuptools.build_meta').

fix

Provide the build_backend argument when creating an instance of BackendHookCaller, for example:

from pyproject_hooks import BackendHookCaller; caller = BackendHookCaller(source_dir='./my_project', build_backend='setuptools.build_meta')

Warnings

breaking In version 1.0.0, the package was renamed from 'pep517' to 'pyproject_hooks'. ↓

fix Update import statements to use 'pyproject_hooks' instead of 'pep517'.

deprecated In version 1.0.0, deprecated modules '.build', '.check', and '.envbuild' were removed. Use the 'build' project for higher-level functionality. ↓

fix Replace usage of '.build', '.check', and '.envbuild' with the 'build' project.

gotcha In version 1.1.0, the 'BackendInvalid' exception was renamed to 'BackendUnavailable'. ↓

fix Update exception handling code to use 'BackendUnavailable' instead of 'BackendInvalid'.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.04s 17.9M

3.10 slim (glibc) - - 0.03s 18M

3.11 alpine (musl) - - 0.09s 19.7M

3.11 slim (glibc) - - 0.07s 20M

3.12 alpine (musl) - - 0.10s 11.6M

3.12 slim (glibc) - - 0.09s 12M

3.13 alpine (musl) - - 0.08s 11.2M

3.13 slim (glibc) - - 0.08s 12M

3.9 alpine (musl) - - 0.05s 17.4M

3.9 slim (glibc) - - 0.04s 18M

Imports

BuildBackendHookCaller
```
from pyproject_hooks import BuildBackendHookCaller
```
Correct import path for BuildBackendHookCaller
BackendUnavailable
```
from pyproject_hooks import BackendUnavailable
```
Correct import path for BackendUnavailable exception
HookMissing
```
from pyproject_hooks import HookMissing
```
Correct import path for HookMissing exception
UnsupportedOperation
```
from pyproject_hooks import UnsupportedOperation
```
Correct import path for UnsupportedOperation exception
default_subprocess_runner
```
from pyproject_hooks import default_subprocess_runner
```
Correct import path for default_subprocess_runner function
quiet_subprocess_runner
```
from pyproject_hooks import quiet_subprocess_runner
```
Correct import path for quiet_subprocess_runner function

Quickstart stale last tested: 2026-04-23

A basic example demonstrating how to use BuildBackendHookCaller to call the 'build_sdist' hook from a pyproject.toml-based project.

import os
from pyproject_hooks import BuildBackendHookCaller

# Set the path to your pyproject.toml file
pyproject_toml_path = os.environ.get('PYPROJECT_TOML_PATH', 'pyproject.toml')

# Initialize the BuildBackendHookCaller
hook_caller = BuildBackendHookCaller(pyproject_toml_path)

# Call the build hook
hook_caller.call_hook('build_sdist')