Skip to content

Wheel builder

A wheel is a binary distribution of a Python package that can be installed directly into an environment.


The builder plugin name is wheel.



Option Default Description
core-metadata-version "2.1" The version of core metadata to use
shared-data A mapping similar to the forced inclusion option corresponding to data that will be installed globally in a given Python environment, usually under sys.prefix
extra-metadata A mapping similar to the forced inclusion option corresponding to extra metadata that will be shipped in a directory named extra_metadata
strict-naming true Whether or not file names should contain the normalized version of the project name
macos-max-compat true Whether or not on macOS, when build hooks have set the infer_tag build data, the wheel name should signal broad support rather than specific versions for newer SDK versions.

Note: The default will become false, and this option eventually removed, sometime after consumers like pip start supporting these newer SDK versions.
bypass-selection false Whether or not to suppress the error when one has not defined any file selection options and all heuristics have failed to determine what to ship


Version Description
standard (default) The latest standardized format
editable A wheel that only ships .pth files or import hooks for real-time development

Default file selection

When the user has not set any file selection options, the project name will be used to determine the package to ship in the following heuristic order:

  1. <NAME>/
  2. src/<NAME>/
  3. <NAME>.py

If none of these heuristics are satisfied, an error will be raised.


Reproducible builds are supported.

Build data

This is data that can be modified by build hooks.

Data Default Description
tag The full tag part of the filename (e.g. py3-none-any), defaulting to a cross-platform wheel with the supported major versions of Python based on project metadata
infer_tag False When tag is not set, this may be enabled to use the one most specific to the platform, Python interpreter, and ABI
pure_python True Whether or not to write metadata indicating that the package does not contain any platform-specific files
dependencies Extra project dependencies
extra_metadata Additional extra-metadata entries, which take precedence in case of conflicts
force_include_editable Similar to the force_include option but specifically for the editable version and takes precedence