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.
- Run pip install pre-commit.
- Run pre-commit –version to confirm it works. The quick start shows output such as pre-commit 4.7.0.
- Create a file named .pre-commit-config.yaml in the root of your project.
- 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.
- Run pre-commit install in your repository.
- 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.
- Fix anything that fails, then stage the changes with git add.
- 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 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.



