# Environment (Python) This guide provides Python-specific environment setup guidance for projects using the Python template toolchain. For shared baseline setup, see the [environment guide](environment.md). ## Tooling 1. Ensure that you have installed either [pipx](https://pipx.pypa.io/stable/) or [uv](https://github.com/astral-sh/uv/blob/main/README.md) for managing Python tools. > **Note:** If installing Pipx via `pip`, use your system Python rather > than a mutable global version managed by Asdf, Mise, or Pyenv. This > reduces the risk that subsequent global version changes break `pipx`. 2. Ensure that you have installed [Copier](https://copier.readthedocs.io/en/stable/) and [Hatch](https://github.com/pypa/hatch/blob/master/README.md). If using Pipx: ```shell pipx install copier hatch ``` If using `uv`: ```shell uv tool install copier uv tool install hatch ``` ## Git Hooks Install Git pre-commit and pre-push hooks with a per-user `pre-commit` installation outside any Hatch development environment, so hooks keep working even when Hatch environments are pruned or rebuilt: ```shell uv tool install pre-commit ``` `pipx install pre-commit` remains functionally compatible, but `uv` is the single documented path to match the tooling section above. Then install the hooks in the repository: ```shell pre-commit install --config .auxiliary/configuration/pre-commit.yaml ``` The hooks themselves delegate to Hatch environments, which are resolved guest-locally at hook time and never shared across the sandbox boundary. If a hook fails because its environment went stale, rebuild the project environments with `hatch env prune` from the project root (all environments are removed and recreated on next use) and re-run the hook. ## Refreshing Environments Remove and rebuild Hatch virtual environments after dependency or interpreter changes: ```shell hatch env prune ``` ## Interpreter Run Python inside the development environment: ```shell hatch --env develop run python ``` ## Shell Open a shell inside the development environment: ```shell hatch --env develop shell ```