{"id":415,"library":"pyproject-hooks","title":"pyproject-hooks","description":"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).","status":"active","version":"1.2.0","language":"python","source_language":"en","source_url":"https://github.com/pypa/pyproject-hooks","tags":["packaging","build","pyproject.toml"],"install":[{"cmd":"pip install pyproject-hooks","lang":"bash","label":"Install pyproject-hooks"}],"dependencies":[{"reason":"Improved interoperability with importlib.metadata in version 1.2.0","package":"importlib.metadata","optional":false}],"imports":[{"note":"Correct import path for BuildBackendHookCaller","symbol":"BuildBackendHookCaller","correct":"from pyproject_hooks import BuildBackendHookCaller"},{"note":"Correct import path for BackendUnavailable exception","symbol":"BackendUnavailable","correct":"from pyproject_hooks import BackendUnavailable"},{"note":"Correct import path for HookMissing exception","symbol":"HookMissing","correct":"from pyproject_hooks import HookMissing"},{"note":"Correct import path for UnsupportedOperation exception","symbol":"UnsupportedOperation","correct":"from pyproject_hooks import UnsupportedOperation"},{"note":"Correct import path for default_subprocess_runner function","symbol":"default_subprocess_runner","correct":"from pyproject_hooks import default_subprocess_runner"},{"note":"Correct import path for quiet_subprocess_runner function","symbol":"quiet_subprocess_runner","correct":"from pyproject_hooks import quiet_subprocess_runner"}],"quickstart":{"code":"import os\nfrom pyproject_hooks import BuildBackendHookCaller\n\n# Set the path to your pyproject.toml file\npyproject_toml_path = os.environ.get('PYPROJECT_TOML_PATH', 'pyproject.toml')\n\n# Initialize the BuildBackendHookCaller\nhook_caller = BuildBackendHookCaller(pyproject_toml_path)\n\n# Call the build hook\nhook_caller.call_hook('build_sdist')","lang":"python","description":"A basic example demonstrating how to use BuildBackendHookCaller to call the 'build_sdist' hook from a pyproject.toml-based project."},"warnings":[{"fix":"Update import statements to use 'pyproject_hooks' instead of 'pep517'.","message":"In version 1.0.0, the package was renamed from 'pep517' to 'pyproject_hooks'.","severity":"breaking","affected_versions":"1.0.0"},{"fix":"Replace usage of '.build', '.check', and '.envbuild' with the 'build' project.","message":"In version 1.0.0, deprecated modules '.build', '.check', and '.envbuild' were removed. Use the 'build' project for higher-level functionality.","severity":"deprecated","affected_versions":"1.0.0"},{"fix":"Update exception handling code to use 'BackendUnavailable' instead of 'BackendInvalid'.","message":"In version 1.1.0, the 'BackendInvalid' exception was renamed to 'BackendUnavailable'.","severity":"gotcha","affected_versions":"1.1.0"}],"env_vars":null,"last_verified":"2026-05-12T13:40:53.474Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"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.","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.","error":"ImportError: cannot import name 'build_wheel' from 'pyproject_hooks'"},{"fix":"Install the package using pip: `pip install 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.","error":"ModuleNotFoundError: No module named 'pyproject_hooks'"},{"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`.","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`.","error":"ModuleNotFoundError: No module named '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')`.","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').","error":"TypeError: BackendHookCaller.__init__ missing 1 required positional argument: 'build_backend'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","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.04,"mem_mb":2.3,"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.03,"mem_mb":2.3,"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.09,"mem_mb":2.7,"disk_size":"19.7M"},{"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.07,"mem_mb":2.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.1,"mem_mb":3.4,"disk_size":"11.6M"},{"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.09,"mem_mb":3.4,"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.08,"mem_mb":3.3,"disk_size":"11.2M"},{"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.08,"mem_mb":3.1,"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.05,"mem_mb":2.5,"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.04,"mem_mb":2.5,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}