pre-commit language: python Environments

language: python tells pre-commit to build a dedicated virtualenv for the hook and install its dependencies.

Python is the most common hook language. pre-commit isolates each python hook in its own venv so tool versions never clash with your project.

What it does

For a language: python hook, pre-commit creates a virtualenv with the pinned interpreter, installs the hook package plus any additional_dependencies, and runs entry inside it. The venv is cached under the pre-commit cache directory keyed by the hook config.

Common usage

.pre-commit-config.yaml

- repo: local
  hooks:
    - id: mypy
      name: mypy
      entry: mypy
      language: python
      language_version: python3.11
      additional_dependencies: ["mypy==1.10.0", "types-requests"]

Keys

Key	What it does
language: python	Build a virtualenv for the hook
language_version	Interpreter, e.g. python3.11
additional_dependencies	Extra pip packages installed into the venv
entry	Command run inside the venv
args	Arguments appended to entry

In CI

The interpreter named by language_version must exist on the runner, so install it (setup-python) before the run. Pin versions in additional_dependencies for reproducibility. After changing dependencies, the cached venv may be stale; pre-commit usually rebuilds on a config hash change, but pre-commit clean forces it.

Common errors in CI

"[ERROR] Executable python3.11 not found" means the pinned interpreter is missing. "ERROR: Could not find a version that satisfies the requirement ..." during env build is a bad or offline additional_dependencies pin. If the hook runs an old tool version after you bumped it, the cached venv is stale; run pre-commit clean.