Hatch Build Scripts Plugin

1.0.0 · active · verified Thu Apr 16

Hatch Build Scripts is a plugin for Hatch, the modern Python project manager, designed to allow users to execute arbitrary shell commands during the build process and include their generated artifacts directly within package distributions. It extends Hatch's build capabilities, providing a flexible way to automate tasks such as compiling assets or generating code, ensuring these outputs are properly bundled. The current stable version is 1.0.0, and releases follow an as-needed cadence to add features and fix bugs.

Common errors

```
Unknown build hook: build-scripts
```
cause This error indicates that Hatch cannot find or load the `hatch-build-scripts` plugin. This typically happens if the plugin is not installed or not correctly listed in your project's `pyproject.toml` as a build-system requirement.

fix First, ensure the package is installed: `pip install hatch-build-scripts`. Then, verify your `pyproject.toml` includes `hatch-build-scripts` in the `[build-system] requires` array: `requires = ["hatchling", "hatch-build-scripts"]`.
```
hatch build exits immediately with no output (on Windows)
```
cause This silent failure on Windows is often due to file locking. An IDE (e.g., VS Code) or another background process might be holding locks on files within the virtual environment or build directory that Hatch needs to modify.

fix Close all IDEs and applications that might be accessing the project directory, then retry `hatch build`. If the problem persists, delete the Hatch cache (`C:\Users\{USERNAME}\AppData\Local\hatch`) and rebuild.
```
Generated files (artifacts) are not included in the final package distribution.
```
cause The `artifacts` patterns in your `pyproject.toml` are incorrect or too restrictive, or the `out_dir` does not match where the files are actually created. Remember, patterns are relative to `work_dir` (default: project root) and then copied to `out_dir` (default: project root).

fix Verify that `artifacts` patterns precisely match the generated files. Use `hatch build --clean` to ensure a fresh build. Double-check `out_dir` to ensure it points to the correct destination relative to your package source. For example, to include in `src/my_package`, set `out_dir = "src/my_package"`.

Warnings

gotcha The PyPI project summary 'Dependency injection without the boilerplate.' is misleading. The actual purpose of `hatch-build-scripts` is to run arbitrary shell commands and include their outputs (artifacts) during a Hatch build, as described in its detailed documentation.
Fix: Refer to the GitHub repository or the detailed PyPI description for the correct understanding of the plugin's functionality.
gotcha Incorrect `pyproject.toml` configuration is a common pitfall. Ensure `hatch-build-scripts` is listed in `build-system.requires` and `tool.hatch.build.hooks.build-scripts` section is correctly formatted with `commands` and `artifacts` keys.
Fix: Carefully review the `quickstart` example and the official documentation for correct TOML syntax and required keys.
gotcha On Windows, `hatch build` can fail silently with no output if an IDE (like VS Code) or another process is locking files within the build environment. This prevents Hatch from modifying necessary files.
Fix: Ensure all IDEs and other applications are closed before running `hatch build`. If the issue persists, try deleting the Hatch cache directory (e.g., `C:\Users\{USERNAME}\AppData\Local\hatch`).
deprecated The `clean_artifacts` parameter in script configuration was introduced in v1.0.0 and defaults to `true`. In older versions, artifacts might not have been cleaned by default, which could lead to stale files being included.
Fix: Upgrade to `hatch-build-scripts>=1.0.0` to leverage automatic artifact cleaning. If on older versions, manually manage artifact cleanup via custom commands.

Install

pip install hatch-build-scripts Install build script plugin

Imports

Build hook configuration

This plugin is configured in `pyproject.toml` under `[tool.hatch.build.hooks.build-scripts]`. It does not require direct Python `import` statements in user code.

Hatch plugins are typically configured declaratively rather than imported programmatically.

Quickstart

To integrate `hatch-build-scripts`, add it to your project's `build-system.requires` in `pyproject.toml`. Then, define scripts under `[[tool.hatch.build.hooks.build-scripts.scripts]]` with `commands` to execute and `artifacts` patterns (like .gitignore) to include in your package. The `out_dir` specifies where artifacts should be placed within the build context.

# pyproject.toml
[build-system]
requires = ["hatchling", "hatch-build-scripts"]
build-backend = "hatchling.build"

[project]
name = "my-project"
version = "0.1.0"

[[tool.hatch.build.hooks.build-scripts.scripts]]
out_dir = "src/my_project"
commands = [
    "echo 'Hello from build script!' > generated_file.txt",
    "python -c \"print('__version__ = \'0.1.0\'')\" > _version.py"
]
artifacts = [
    "generated_file.txt",
    "_version.py"
]

# To run the build:
# hatch build --clean

view raw JSON →