Skip to content

Wheel builder

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

Configuration

The builder plugin name is wheel.

[tool.hatch.build.targets.wheel]

[build.targets.wheel]

Options

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.

Versions

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>/__init__.py
  2. src/<NAME>/__init__.py
  3. <NAME>.py
  4. <NAMESPACE>/<NAME>/__init__.py
  5. Otherwise, every Python package and file that does not start with the word test will be included

Reproducibility

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