How to define environments from multiple files.

[ketozhang]

Currently if I have both pyproject.toml and hatch.toml in the same project/directory, then hatch.toml takes precedence and the config is overridden (replaced).

My use case for this is that I want pyproject.toml to be in git, but keep hatch.toml locally, such that I can configure my own dev environment without affecting others. A choice I make in my dev environment, that others may not, is I like my primary development venv to be in .venv. Others may include the extra packages I like to have in my dev environment (e.g., ipython).

Is this possible by other means?

Example

# pyproject.toml
[tool.hatch.envs.default]
python="3.12"

[tool.hatch.envs.test]
extra-dependencies = ['pytest']

# hatch.toml
[envs.dev]
python="3.13"
path=".venv"
extra-dependencies = ['ipython']

[tayfuryldz]

Hatch does not merge project environment configuration from pyproject.toml and hatch.toml; they are alternative project configuration locations. So using a local hatch.toml as an overlay on the checked-in tool.hatch.envs tables is not a supported composition mechanism.

For this use case I would keep the shared environments in pyproject.toml and model optional developer tooling as another inherited environment, for example a dev environment inheriting from default and adding ipython. That is safe to check in even if only some developers use it: nobody creates or enters dev unless they select it.

The machine-specific part is the .venv location. If the motivation for keeping the entire table private is just avoiding a local .venv preference, isolate that preference rather than duplicating all environment definitions into an ignored hatch.toml.

Another practical option is to keep a complete local alternative project config outside version control and select it deliberately when needed, but it must contain the environment configuration you want; it is a replacement, not a delta file.

So the important constraint is: don't expect the two project config files to deep-merge. Keep shared/inheritable environment semantics in the project config and machine-local choices separate where possible.