pre-commit "RuntimeError: ... Cannot install ... environment" in CI

pre-commit builds an isolated environment per hook. When that setup command fails (a bad additional dependency, a compile error, or a missing runtime) it raises a RuntimeError and cannot install the environment.

What this error means

The run fails with "An unexpected error has occurred: RuntimeError:" and a message that it could not install the environment for a hook, pointing at the pre-commit log.

An unexpected error has occurred: RuntimeError:
Cannot install the flake8 environment: pip returned an error.
Check the log at /root/.cache/pre-commit/pre-commit.log

Common causes

A bad additional_dependencies entry

An additional_dependencies package version does not exist or conflicts, so the env build fails while installing the hook plugins.

A source build needs tooling the runner lacks

A dependency with C extensions tries to compile and the runner has no compiler or headers, failing the environment setup.

How to fix it

Correct the additional dependencies

1. Open the pre-commit log to see which install command failed.
2. Fix or pin the offending additional_dependencies version.
3. Re-run so the environment builds.

- repo: https://github.com/pycqa/flake8
  rev: 7.1.0
  hooks:
    - id: flake8
      additional_dependencies: ['flake8-bugbear==24.4.26']

Provide build tooling when a source build is required

Install a compiler and headers before pre-commit so an extension build in the hook env succeeds.

sudo apt-get update && sudo apt-get install -y build-essential python3-dev

How to prevent it

• Pin additional_dependencies to versions you know publish wheels.
• Cache PRE_COMMIT_HOME so a good env is reused instead of rebuilt.
• Keep the hook language runtime available on the runner.

Related guides