pep517

library0.13.1pypypi✓ verified 24d ago

pep517 provides low-level wrappers to interact with Python package build backends that implement PEP 517 hooks. It is primarily used by build frontends like `pip` and `build` to orchestrate the build process (e.g., building source distributions, wheels). The current stable version is 0.13.1, and releases occur as needed to address issues or align with packaging standards, typically not on a strict cadence.

devops

pip install pep517

github ↗package ↗

INSTALL

IMPORT

SIG · PEP517

pep517

devopspythonv0.13.1

Install

1.5s avg

Import

68ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.13.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.070s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.066s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Pep517HookCaller

✓ from pep517.wrappers import Pep517HookCaller

BuildBackendException

✓ from pep517.wrappers import BuildBackendException

This quickstart demonstrates how to programmatically use `pep517` to interact with a build backend. It creates a temporary project, defines a `pyproject.toml` using `setuptools.build_meta`, and then uses `Pep517HookCaller` to retrieve the build requirements for a wheel. This illustrates the low-level interaction pattern that build frontends employ.

import os import tempfile from pathlib import Path import shutil from pep517.wrappers import Pep517HookCaller, BuildBackendException # Create a dummy project directory with a pyproject.toml # In a real scenario, this would be an existing project. project_dir = Path(tempfile.mkdtemp()) try: (project_dir / "pyproject.toml").write_text(""" [build-system] requires = ["setuptools>=61.0.0", "wheel"] build-backend = "setuptools.build_meta" """) (project_dir / "src").mkdir() (project_dir / "src" / "__init__.py").write_text("") (project_dir / "src" / "my_module.py").write_text("VERSION = '0.1.0'") # Instantiate a Pep517HookCaller to interact with the backend # For setuptools.build_meta, backend_path is typically empty, # meaning it's expected to be importable directly. caller = Pep517HookCaller( source_dir=project_dir, build_backend="setuptools.build_meta", backend_path=[] ) # Example: Get build requirements for a wheel # config_settings can be an empty dict if no specific settings are needed requires = caller.get_requires_for_build_wheel(config_settings={}) print(f"Build requires for wheel: {requires}") except BuildBackendException as e: print(f"Backend error: {e}") except Exception as e: print(f"An unexpected error occurred: {e}") finally: # Clean up temporary directory if project_dir.exists(): shutil.rmtree(project_dir)

Debug

Known issues

gotchapep517 is a low-level library designed for build *frontends* (like `pip` or `build`). It is generally not intended for direct use by end-users looking to simply build a Python package.

fix

If you want to build a Python package, use a higher-level tool like `python -m build` (from the `build` library) or `pip install .`.

affects: All versions

gotchaThe `build-backend` specified in `pyproject.toml` must be importable in the Python environment where `pep517` is executed. Incorrect `backend_path` or an uninstalled backend will lead to `BackendUnavailable` or `BackendFailed` exceptions.

fix

Ensure that the required build backend (e.g., `setuptools`, `hatchling`, `flit_core`) is installed in your virtual environment. If the backend is local or in a non-standard location, provide the correct directories in the `backend_path` argument to `Pep517HookCaller`.

affects: All versions

gotchaThe `config_settings` dictionary passed to backend hooks (e.g., `build_wheel`, `get_requires_for_build_wheel`) is specific to each build backend. There is no universal standard for these settings, and passing unsupported options can lead to unexpected behavior or errors.

fix

Consult the documentation of the specific build backend you are interacting with (e.g., `setuptools`, `hatchling`) to understand which `config_settings` it supports and their expected values.

affects: All versions

Errors

Common errors & fixes

ERROR: Could not build wheels for X which use PEP 517 and cannot be installed directly

This generic error indicates a build failure for a package using PEP 517, often due to an outdated `pip` version, missing system-level build tools (like C compilers or development headers), or the absence of pre-built wheels for your specific Python version and operating system.

fix

Upgrade `pip` (`python -m pip install --upgrade pip`), install necessary system dependencies (e.g., `sudo apt-get install python3-dev build-essential` on Debian/Ubuntu, or specific library development packages as indicated in the verbose error log), or ensure your Python version is supported by the package. As a last resort, `pip install --no-use-pep517 <package-name>` might work if the issue is a package's improper PEP 517 support, though this is generally discouraged.

ModuleNotFoundError: No module named 'Y'

This occurs when a build dependency required by the package's build backend (e.g., `setuptools`, `packaging`, `wheel`, or a system tool like `cmake`, or even `distutils` in Python 3.12+) is not found in the isolated build environment managed by `pep517`. For `distutils`, this is particularly common in Python 3.12+ where it was removed.

fix

For package developers, ensure all build dependencies are correctly listed in the `build-system.requires` section of `pyproject.toml`. For users, if upgrading `pip` doesn't resolve it, the package might need to be updated to a version compatible with your Python (e.g., NumPy 1.26+ for Python 3.12+ to address `distutils` removal). You might also need to install missing system-level build tools if they are the root cause.

ERROR: subprocess-exited-with-error × Getting requirements to build wheel did not run successfully.

This indicates a failure during the initial phase of the PEP 517 build process where the build backend attempts to determine its own build requirements. The underlying cause is typically detailed in the output immediately preceding this error, often a `ModuleNotFoundError`, a `SyntaxError` in a `setup.py` (if the backend uses it), or a missing system dependency.

fix

Carefully examine the detailed error messages in the output preceding this line to identify the specific failure. This will guide you to install missing Python packages, required system-level tools (like compilers or native libraries), or report the issue to the package maintainers if the `pyproject.toml` configuration is incorrect.

AttributeError: 'InstallRequirement' object has no attribute 'use_pep517'

This specific error arises when a tool (such as `pip-tools`) that relies on `pip`'s internal APIs encounters a newer version of `pip` (e.g., pip 25.3+) where the `use_pep517` attribute of `InstallRequirement` has been removed. This signifies an incompatibility between the tool and the `pip` version.

fix

Downgrade `pip` to a version compatible with the tool (e.g., `pip install "pip<25.3"` if `pip-tools` is the affected utility) or upgrade the tool itself to a version that supports the newer `pip` APIs.

Upgrade

Version history

0.13.1latest on PyPI · released Nov 8, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/pypa/pep517 ↗

packagehttps://pypi.org/project/pep517/ ↗