# What a build requirement declaration does (and does not) establish

> Source: <https://discuss.huggingface.co/t/what-a-build-requirement-declaration-does-and-does-not-establish/191892#post_1>
> Published: 2026-11-15 09:12:00+00:00

For maintainers of Python ML packages with custom build scripts: a requirement in `pyproject.toml` answers what the project declares. It does not, by itself, tell you what a particular non-isolated build route put into its environment.

Here’s a synthetic example. The project has:

```
[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"
```

Its `scripts/build.sh` runs `python -m pip wheel . --no-build-isolation`. The environment declaration mapped to that script, `reqs/build.pip`, names `setuptools>=68` but does not name `wheel`.

Those facts support a narrow conclusion: if `reqs/build.pip` is the *complete* set of environment declarations for that non-isolated route, `wheel` is a **declaration gap** for that route. They do not prove `wheel` was absent at runtime or that the build failed; it could have been installed outside the mapped declarations. If the mapping is incomplete or the script’s route is unclear, the honest result is **unknown**. For a separately mapped isolated route, check the literal `[build-system].requires` declarations instead; don’t assume the frontend actually used isolation merely because the project declares build requirements.

We built a small, local, read-only Yumi CLI to make those boundaries explicit. The maintainer supplies the repository root and a route manifest naming the entrypoint, declaration files, isolation mode and whether those files are complete:

```
{
  "schema": 1,
  "routes": [{
    "name": "wheel script",
    "isolation": "non-isolated",
    "entrypoints": ["scripts/build.sh"],
    "declarations": ["reqs/build.pip"],
    "declarations_complete": true
  }]
}
```

Run `python -B declared_build_environment_evidence.py --root /path/to/repo --routes /path/to/routes.json` with Python 3.11+. The [source and input format](https://github.com/noqt/noqt/blob/5a3ef6ee0a3e11a0de6ba2b96b4fcf7a284e039d/yumi/declared-build-environment/README.md) are public. It reads explicitly mapped files, compares literal package names, and binds results to source and route digests. It does not run a build, install dependencies or resolve version constraints.

The work is still in choosing the correct route and making an honest completeness assertion. You can do the same inspection manually; the CLI helps keep the distinction between `DECLARED`, `DECLARATION_GAP` and `UNKNOWN` explicit when a repository has several build paths. This example is illustrative, not evidence from a user build. Prepared with AI assistance on behalf of noqt.