Where Does Hatch Store Environments and Config?
Where the Hatch Python packaging tool keeps its environments folder, config.toml, and build cache.
Last updated
Hatch centers on a data root: ~/.local/share/hatch on Linux (and macOS), %LOCALAPPDATA%\hatch on Windows. config.toml sets behavior while env/virtual/ holds the actual environments.
Environments are disposable by design since pyproject.toml declares them. Back up the config and the project files; recreate envs with hatch env create. The build cache beside them speeds rebuilds and clears safely when disk runs low. The env show command prints per environment paths. Scripts run inside envs automatically.
Where Hatch stores this, by platform
~/.local/share/hatch
config.toml plus env/virtual/ environments and build cache here. Honors $XDG_DATA_HOME and HATCH_DATA_DIR overrides. The hatch config show command prints the file it actually read.
~/.local/share/hatch
Same tree as Linux. Homebrew and pipx installs share it, so switching installers keeps environments. Project local .venv folders stay separate and take precedence when present.
%LOCALAPPDATA%\hatch
Same layout under LocalAppData. Paste the path into Explorer. HATCH_DATA_DIR relocates the root anywhere, including shared disks for lab machines.
Frequently asked questions
where is the hatch config file
In config.toml under the Hatch data root (~/.local/share/hatch on Linux). It holds mode, dirs, and template settings. hatch config show prints the live file with its path, which settles XDG override doubts instantly.
where are hatch virtualenvs stored
Under env/virtual/ inside the data root, one folder per environment. hatch env prune removes stale ones; deleting folders by hand works with Hatch closed. Project pins in pyproject.toml decide recreation, so environments are disposable by design.
can hatch environments live per project
Yes through the data root relocation (HATCH_DATA_DIR) or per project storage. The default keeps all projects in one tree, which suits single dev machines. CI caches the data dir between runs for speed.
Notice an outdated path? Let us know.