pypa-hatch/docs/plugins/builder/wheel.md

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]

Options

Option	Default	Description
core-metadata-version	"2.3"	The version of core metadata to use
shared-data		A mapping similar to the forced inclusion option corresponding to the data subdirectory within the standard data directory that will be installed globally in a given Python environment, usually under #!python sys.prefix
shared-scripts		A mapping similar to the forced inclusion option corresponding to the scripts subdirectory within the standard data directory that will be installed in a given Python environment, usually under Scripts on Windows or bin otherwise, and would normally be available on PATH
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	false	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: This option will eventually be removed.
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

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

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

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	#!python 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	#!python True	Whether or not to write metadata indicating that the package does not contain any platform-specific files
dependencies		Extra project dependencies
shared_data		Additional shared-data entries, which take precedence in case of conflicts
shared_scripts		Additional shared-scripts entries, which take precedence in case of conflicts
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