pypa-hatch/docs/plugins/builder.md

Builder plugins

---

See the documentation for build configuration.

Built-in

Wheel

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.

=== ":octicons-file-code-16: pyproject.toml"

```toml
[tool.hatch.build.targets.wheel]
```

=== ":octicons-file-code-16: hatch.toml"

```toml
[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 explicit selection option corresponding to data that will be installed globally in a given Python environment, usually under #!python sys.prefix
extra-metadata		A mapping similar to the explicit selection option corresponding to extra metadata that will be shipped in a directory named extra_metadata

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. <PACKAGE>/__init__.py
2. src/<PACKAGE>/__init__.py
3. <NAMESPACE>/<PACKAGE>/__init__.py
4. 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	#!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
force_include_editable		Similar to the force_include option but specifically for the editable version

Source distribution

A source distribution, or sdist, is an archive of Python "source code". Although largely unspecified, by convention it should include everything that is required to build a wheel without making network requests.

Configuration

The builder plugin name is sdist.

=== ":octicons-file-code-16: pyproject.toml"

```toml
[tool.hatch.build.targets.sdist]
```

=== ":octicons-file-code-16: hatch.toml"

```toml
[build.targets.sdist]
```

Options

Option	Default	Description
core-metadata-version	"2.1"	The version of core metadata to use
support-legacy	false	Whether or not to include a setup.py file to support legacy installation mechanisms

Versions

Version	Description
standard (default)	The latest conventional format

Default file selection

When the user has not set any file selection options, all files that are not ignored by your VCS will be included.

Reproducibility

Reproducible builds are supported.

Build data

This is data that can be modified by build hooks.

Data	Default	Description
dependencies		Extra project dependencies

Custom

This is a custom class in a given Python file that inherits from the BuilderInterface.

Configuration

The builder plugin name is custom.

=== ":octicons-file-code-16: pyproject.toml"

```toml
[tool.hatch.build.targets.custom]
```

=== ":octicons-file-code-16: hatch.toml"

```toml
[build.targets.custom]
```

An option path is used to specify the path of the Python file, defaulting to hatch_build.py.

Example

=== ":octicons-file-code-16: hatch_build.py"

```python
from hatchling.builders.plugin.interface import BuilderInterface


class CustomBuilder(BuilderInterface):
    ...
```

If multiple subclasses are found, you must define a function named get_builder that returns the desired builder.

!!! note Any defined PLUGIN_NAME is ignored and will always be custom.

::: hatchling.builders.plugin.interface.BuilderInterface selection: members: - PLUGIN_NAME - app - root - build_config - target_config - config - get_config_class - get_version_api - get_default_versions - clean - recurse_included_files - get_default_build_data