.pre-commit-config.yaml: The Config File

.pre-commit-config.yaml is the file at the repo root that tells pre-commit which hooks to run.

Everything pre-commit does is driven by this YAML file. Get the structure right and the rest follows; a single bad key triggers InvalidConfigError.

What it does

The config maps a list of repos, each with a url, a rev (pinned version), and a hooks list selecting hook ids. Top-level keys like default_stages, default_language_version, exclude, and ci tune behavior across all hooks.

Common usage

.pre-commit-config.yaml

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
  - repo: https://github.com/psf/black
    rev: 24.4.2
    hooks:
      - id: black

Top-level keys

Key	What it does
repos	List of hook repositories to run
default_stages	Stages hooks run at unless overridden
default_language_version	Default interpreter version per language
exclude	Global regex of files to skip
fail_fast	Stop after the first failing hook
ci	Settings for pre-commit.ci (autofix, autoupdate_schedule)

Common errors in CI

"InvalidConfigError: ... is not a valid pre-commit config" usually points at a wrong key name or wrong indentation; the message names the failing schema rule. "while parsing a block mapping" is a raw YAML syntax error (tabs, bad indentation). "Expected one of ... but got ..." means a value type is off, e.g. rev given as a number instead of a quoted string. Quote rev values that look numeric.