Build configuration¶
All build configuration is defined in the tool.hatch.build table.
Build targets are defined as sections within tool.hatch.build.targets:
[tool.hatch.build.targets.<TARGET_NAME>]
[build.targets.<TARGET_NAME>]
For each build target you may override any of the defaults set in the top-level tool.hatch.build table.
Build system¶
To be compatible with the broader Python packaging ecosystem, you must define the build system as follows:
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
The version of hatchling defined here will be used to build all targets.
Hatchling is a PEP 517/PEP 660 compatible build system and is a dependency of Hatch itself.
File selection¶
VCS¶
By default, Hatch will respect any .gitignore file located at your project's root. Set ignore-vcs to true to disable this behavior:
[tool.hatch.build]
ignore-vcs = true
[build]
ignore-vcs = true
Patterns¶
You can set the include and exclude options to select exactly which files will be shipped in each build, with exclude taking precedence. Every entry represents a Git-style glob pattern.
For example, the following configuration:
[tool.hatch.build]
include = [
"pkg/*.py",
"/tests",
]
exclude = [
"*.json",
"pkg/_compat.py",
]
[build]
include = [
"pkg/*.py",
"/tests",
]
exclude = [
"*.json",
"pkg/_compat.py",
]
will exclude every file with a .json extension, and will include everything under a tests directory located at the root and every file with a .py extension that is directly under a pkg directory located at the root except for _compat.py.
Packages¶
The packages option can be used to include specific Python packages. This option is semantically equivalent to include except that every entry is a simple relative path and the shipped path will be collapsed to only include the final component.
So for example, if you want to ship a package foo that is stored in a directory src you would do:
[tool.hatch.build.targets.wheel]
packages = ["src/foo"]
[build.targets.wheel]
packages = ["src/foo"]
Artifacts¶
If you want to include files that are ignored by your VCS, such as those that might be created by build hooks, you can use the artifacts option. This option is semantically equivalent to include.
[tool.hatch.build]
artifacts = [
"*.so",
"*.dll",
]
[build]
artifacts = [
"*.so",
"*.dll",
]
Default file selection¶
If no file selection options are provided, then what gets included is determined by each build target.
Reproducible builds¶
By default, build targets will build in a reproducible manner provided that they support that behavior. To disable this, set reproducible to false:
[tool.hatch.build]
reproducible = false
[build]
reproducible = false
When enabled, the SOURCE_DATE_EPOCH environment variable will be used for all build timestamps. If not set, then Hatch will use an unchanging default value.
Output directory¶
When the output directory is not provided to the build command, the dist directory will be used by default. You can change the default to a different directory using a relative or absolute path like so:
[tool.hatch.build]
directory = "<PATH>"
[build]
directory = "<PATH>"
Dev mode¶
In most cases, dev mode environment installations or editable installs in general will work as expected. However, for some project layouts you need to explicitly define which directories to add to Python's search path, such as for namespace packages.
You can do this with the dev-mode-dirs option:
[tool.hatch.build]
dev-mode-dirs = ["."]
[build]
dev-mode-dirs = ["."]
Build targets¶
A build target can be provided by any builder plugin. There are three built-in build targets: wheel, sdist, and custom.
Dependencies¶
You can specify additional dependencies that will be installed in each build environment, such as for third party builders:
[tool.hatch.build.targets.your-target-name]
dependencies = [
"your-builder-plugin"
]
[build.targets.your-target-name]
dependencies = [
"your-builder-plugin"
]
Versions¶
If a build target supports multiple build strategies or if there are major changes over time, you can specify exactly which versions you want to build using the versions option, which may be defined as either an array of strings or a comma-separated string:
[tool.hatch.build.targets.<TARGET_NAME>]
versions = [
"v1",
"beta-feature",
]
[build.targets.<TARGET_NAME>]
versions = [
"v1",
"beta-feature",
]
Build hooks¶
A build hook defines code that will be executed at various stages of the build process and can be provided by any build hook plugin. There is one built-in build hook: custom.
Build hooks can be applied either globally:
[tool.hatch.build.hooks.<HOOK_NAME>]
[build.hooks.<HOOK_NAME>]
or to specific build targets:
[tool.hatch.build.targets.<TARGET_NAME>.hooks.<HOOK_NAME>]
[build.targets.<TARGET_NAME>.hooks.<HOOK_NAME>]
Dependencies¶
You can specify additional dependencies that will be installed in each build environment, such as for third party build hooks:
[tool.hatch.build.hooks.your-hook-name]
dependencies = [
"your-build-hook-plugin"
]
[build.hooks.your-hook-name]
dependencies = [
"your-build-hook-plugin"
]
Order of execution¶
For each build target, build hooks execute in the order in which they are defined, starting with target-specific hooks.
As an example, for the following configuration:
[tool.hatch.build.hooks.hook3]
[tool.hatch.build.hooks.hook1]
[tool.hatch.build.targets.foo.hooks.hook2]
[build.hooks.hook3]
[build.hooks.hook1]
[build.targets.foo.hooks.hook2]
When target foo is built, build hook hook2 will be executed first, followed by hook3, and then finally hook1.
Conditional execution¶
If you want to disable a build hook by default and control its use by environment variables, you can do so by setting the enable-by-default option to false:
[tool.hatch.build.hooks.<HOOK_NAME>]
enable-by-default = false
[build.hooks.<HOOK_NAME>]
enable-by-default = false
Environment variables¶
| Variable | Default | Description |
|---|---|---|
HATCH_BUILD_CLEAN | false | Whether or not existing artifacts should first be removed |
HATCH_BUILD_CLEAN_HOOKS_AFTER | false | Whether or not build hook artifacts should be removed after each build |
HATCH_BUILD_HOOKS_ONLY | false | Whether or not to only execute build hooks |
HATCH_BUILD_NO_HOOKS | false | Whether or not to disable all build hooks; this takes precedence over other options |
HATCH_BUILD_HOOKS_ENABLE | false | Whether or not to enable all build hooks |
HATCH_BUILD_HOOK_ENABLE_<HOOK_NAME> | false | |
HATCH_BUILD_LOCATION | dist | The location with which to build the targets; only used by the build command |