Configuration¶

Use a project config to choose hooks and customize their options. If you need a starter config, follow the Quickstart. This page covers editing, validating, and updating that config; Running Hooks covers executing it.

Choose a config file¶

prek reads one config per project. Keep an existing .pre-commit-config.yaml, or use prek.toml for a new setup. Both formats describe the same configuration model.

Filename	Format
`prek.toml`	TOML
`.pre-commit-config.yaml`	YAML
`.pre-commit-config.yml`	YAML

If several of these files exist in one directory, prek uses the first one in the order above. Use one file per project to make it clear which config applies.

To convert a YAML config, run prek util yaml-to-toml. The conversion does not preserve YAML comments. If the config must also work with upstream pre-commit, keep YAML and read Sharing a config with pre-commit.

Add and configure hooks¶

List hook repositories under repos, pin each remote repository to a rev, and select its hooks by id:

prek.toml.pre-commit-config.yaml

[[repos]]
repo = "https://github.com/pre-commit/pre-commit-hooks"
rev = "v6.0.0"
hooks = [
  { id = "trailing-whitespace" },
  { id = "check-added-large-files", args = ["--maxkb=1024"] },
]

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v6.0.0
    hooks:
      - id: trailing-whitespace
      - id: check-added-large-files
        args: [--maxkb=1024]

The hook repository supplies defaults such as the command and language. Add options to a hook entry to customize it. Here, args changes the large-file limit to 1024 KB. Consult the hook's documentation for the arguments it accepts.

You can also use:

Local Hooks to define commands directly in the project config.
Built-in Hooks to use hooks bundled with prek.

TOML and YAML syntax¶

For larger TOML hook entries, use an array of tables instead of an inline table. This is equivalent to the large-file hook above:

[[repos]]
repo = "https://github.com/pre-commit/pre-commit-hooks"
rev = "v6.0.0"

[[repos.hooks]]
id = "check-added-large-files"
args = ["--maxkb=1024"]

prek also accepts multiline inline tables from TOML 1.1. If an editor does not support that syntax, use the array-of-tables form above.

In YAML, quote regular expressions containing backslashes, for example files: '\.rs$'. YAML anchors, aliases, and merge keys can reuse repeated configuration.

Choose which files and stages to check¶

A hook's files, exclude, types, types_or, and exclude_types options control which files it receives. Top-level files and exclude apply to every hook in that project. For example, exclude generated files from all hooks by adding this at the top of the config, before the repository entries:

prek.toml.pre-commit-config.yaml

exclude = '^generated/'

exclude: '^generated/'

files and exclude accept regular expressions or prek's explicit glob form. Type filters use file type tags; inspect a file's tags with:

prek util identify path/to/file

A hook's stages limits the Git hook stages where it runs. To install the corresponding Git shim, use default_install_hook_types or prek install --hook-type. Setting stages alone does not install a shim.

See the Configuration Reference for filter combinations, stage names, and all available options.

Config location and scope¶

prek searches upward from the current directory for a config, stopping at the Git repository root. The first config found defines the workspace root; prek then discovers nested projects below it.

Each project applies its config independently. A parent's filters do not disable a child's hooks, and a child config does not override its parent. See Monorepos for setting up and selecting nested projects, or the Workspace Reference for discovery and file-scope rules.

Passing --config selects one config and disables workspace discovery. Hooks then run from the Git repository root with repository-relative paths.

Validate changes¶

After editing a config, validate it and run the hooks against existing files:

prek validate-config prek.toml
prek run --all-files

Use the repository's YAML config filename instead if applicable. prek validate-config accepts one or more config files. See Debugging if a hook is skipped unexpectedly.

If you want IDE completion / validation, prek publishes a JSON Schema through the JSON Schema Store, so some editors may pick it up automatically.

Update hook versions¶

Update pinned remote hook revisions with:

prek update

Review the config diff, then run prek run --all-files to check the updated hooks against the repository. Use prek update --check to check for available updates without changing the config. See prek update for selecting repositories and controlling updates.

User settings¶

prek also reads an optional user-level global config from the platform config directory:

Linux and macOS: ~/.config/prek/prek.toml (or $XDG_CONFIG_HOME/prek/prek.toml when XDG_CONFIG_HOME is set)
Windows: %APPDATA%\prek\prek.toml

This file is for user-level prek settings, not hook definitions. Project hooks still live in the project config files described above. For the supported global settings, see the configuration reference.

Existing pre-commit YAML configs work in prek. To use the same config with both tools, keep the YAML format and avoid prek-only extensions. Upstream pre-commit may warn about unknown keys or reject unsupported features.

See Compatibility for the features that affect portability and Differences for broader behavior differences.