Setting Up Pre-Commit Hooks Step by Step

how to set up pre-commit hooks

Worried that trivial mistakes keep slipping into your commits? Here is how to set up pre-commit hooks: install the pre-commit tool, add a .pre-commit-config.yaml file, then run pre-commit install. Your checks run on every commit.

If you are comparing tooling more widely, see our guide to the best developer tools.

Item Value
Install command pip install pre-commit
Config file .pre-commit-config.yaml in the project root
Activate the git hook pre-commit install
Check every file pre-commit run –all-files
Version shown in the quick start pre-commit 4.7.0
Flag that skips hooks git commit –no-verify

These figures come from the official pre-commit documentation and the pydevtools handbook. Commands and versions can change, so check the source before you rely on them.

What pre-commit hooks do

A git hook is a script that Git runs at a set point in your workflow. A pre-commit hook runs after you stage changes but before Git creates the commit, and if it exits with a non-zero status, Git aborts the commit so you can fix the problem first.

Writing and sharing those scripts by hand gets messy, which is why most teams use the pre-commit framework. The pre-commit documentation describes it as a multi-language package manager for pre-commit hooks: you list the hooks you want, and it installs and runs them for you.

The typical payoff is catching small things early, such as missing semicolons, trailing whitespace and debug statements. That leaves your code reviewer free to focus on the architecture of a change instead of trivial style nitpicks.

Common starter checks include:

  • Trimming trailing whitespace.
  • Making sure files end with a newline.
  • Checking that YAML files parse.
  • Running a formatter on your source code.

That last item is where many people start, so if the idea is new to you, read what is a code formatter before you pick one.

Install pre-commit and create the config file

The simplest route is pip. The documentation gives the command pip install pre-commit, and for a Python project you can also list pre-commit in your requirements.txt or requirements-dev.txt. The tool is designed to not require root access, so you can install hooks without administrator rights.

  1. Run pip install pre-commit.
  2. Run pre-commit –version to confirm it works. The quick start shows output such as pre-commit 4.7.0.
  3. Create a file named .pre-commit-config.yaml in the root of your project.
  4. Add the repositories and hooks you want, or generate a basic file with pre-commit sample-config.

The config file is a list of repositories, and each one names a pinned revision and the hooks you want from it. These are the keys you will use most:

Key What it does
repo The repository URL to clone from, or a special value such as local or meta
rev The revision or tag to clone at
hooks A list of hook mappings for that repository
id Which hook from the repository to use

The official example starts with the pre-commit-hooks repository and enables the check-yaml, end-of-file-fixer and trailing-whitespace hooks. It then adds a Python formatter, though the documentation stresses that pre-commit works for any programming language.

Pinning the revision means everyone runs the same hook code, because pre-commit clones remote hook repositories at the configured rev. Commit the config file so your teammates get it too.

Install the git hook and run it on all files

The config file alone does nothing until you wire it into Git. Running pre-commit install writes the hook script into your repository, and the tool reports that it is installed at .git/hooks/pre-commit and will now run automatically on git commit.

  1. Run pre-commit install in your repository.
  2. Run pre-commit run –all-files once. By default pre-commit only checks changed files during a commit, so this brings the existing code up to the same standard.
  3. Fix anything that fails, then stage the changes with git add.
  4. Commit as usual with git commit and let the hooks run.

Some hooks fix files themselves. When the trailing-whitespace hook edits a file, the docs example shows a failure with the message that files were modified by this hook. In that case, add and commit again so that all hooks pass.

how to set up pre-commit hooks Laptop keyboard
A close view shows an illuminated laptop keyboard and the edge of its trackpad.

How do you keep hooks fast and up to date?

Hooks that annoy people get skipped, so a little care at the start pays off. These habits come up repeatedly in the guides we reviewed:

  • Keep hooks fast. Graphite advises making sure hooks run quickly so they do not slow down the commit process.
  • Start small. OpenReplay suggests beginning with non-intrusive hooks such as trailing whitespace removal, then adding stricter checks gradually.
  • Share the config. Keep .pre-commit-config.yaml in your repository so all team members use the same hooks.
  • Update deliberately. pre-commit autoupdate refreshes the configured hook revisions, so run it on purpose rather than by accident.
  • Stop at the first failure if you prefer. Setting fail_fast to true makes pre-commit stop running hooks after the first failure.

Editor settings are a separate layer that works alongside hooks. If your team also wants consistent indentation and line endings while people type, read what is editorconfig to see how the two fit together.

Why CI still needs to run the same checks

Local hooks are a convenience, not a guarantee. According to the pydevtools handbook, contributors can skip local hooks with git commit –no-verify or by never installing them. Without pre-commit installed, hooks won’t run locally and the code will still commit.

That is why the same handbook notes that pre-commit does not replace pytest, a type checker or CI. A practical safety net is to run pre-commit run –all-files as a CI step so that merge-blocking checks do not depend on each person’s setup.

Expect a few trade-offs as well. First runs can be slower while hook repositories and environments install, and skipping hooks is highly not recommended because the checks are there for a reason. If speed is a concern, the handbook also describes prek, a compatible reimplementation that reads the same configuration format.

Frequently asked questions

Do I need root access to use pre-commit?

Show answer

No. The documentation says pre-commit is specifically designed to not require root access, and it can download and build the tools a hook needs on its own.

Why did my commit fail and change my files?

Show answer

A hook such as trailing-whitespace can fix files and then report a failure. Stage the modified files with git add and commit again.

Can I use pre-commit with languages other than Python?

Show answer

Yes. It is a multi-language framework, and its documentation says it works for any programming language, so you can mix Python, JavaScript and other tools in one config file.

Does pre-commit replace my CI pipeline?

Show answer

No. Contributors can bypass local hooks, so keep running the checks in CI as well, for example with pre-commit run –all-files.