{"id":9030,"library":"hatch-build-scripts","title":"Hatch Build Scripts Plugin","description":"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.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/rmorshea/hatch-build-scripts","tags":["hatch","plugin","build","packaging","scripts","artifacts","automation"],"install":[{"cmd":"pip install hatch-build-scripts","lang":"bash","label":"Install build script plugin"}],"dependencies":[{"reason":"Required build backend, typically listed in `build-system.requires` in `pyproject.toml`.","package":"hatchling","optional":false},{"reason":"The core project manager that orchestrates the build process and utilizes this plugin.","package":"hatch","optional":false}],"imports":[{"note":"Hatch plugins are typically configured declaratively rather than imported programmatically.","symbol":"Build hook configuration","correct":"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."}],"quickstart":{"code":"# pyproject.toml\n[build-system]\nrequires = [\"hatchling\", \"hatch-build-scripts\"]\nbuild-backend = \"hatchling.build\"\n\n[project]\nname = \"my-project\"\nversion = \"0.1.0\"\n\n[[tool.hatch.build.hooks.build-scripts.scripts]]\nout_dir = \"src/my_project\"\ncommands = [\n    \"echo 'Hello from build script!' > generated_file.txt\",\n    \"python -c \\\"print('__version__ = \\'0.1.0\\'')\\\" > _version.py\"\n]\nartifacts = [\n    \"generated_file.txt\",\n    \"_version.py\"\n]\n\n# To run the build:\n# hatch build --clean","lang":"toml","description":"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."},"warnings":[{"fix":"Refer to the GitHub repository or the detailed PyPI description for the correct understanding of the plugin's functionality.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully review the `quickstart` example and the official documentation for correct TOML syntax and required keys.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<1.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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\"]`.","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.","error":"Unknown build hook: build-scripts"},{"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.","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.","error":"hatch build exits immediately with no output (on Windows)"},{"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\"`.","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).","error":"Generated files (artifacts) are not included in the final package distribution."}]}