---
url: /developers/tools/pre-commit.md
---
# Pre-Commit Guide

Open Library uses [`pre-commit`](https://pre-commit.com/) hooks to enforce formatting and code quality standards. All contributors must have `pre-commit` installed locally — it catches issues before you push and saves everyone time and frustration.

## Installing `pre-commit`

Install `pre-commit` using [`uv`](https://docs.astral.sh/uv/), a fast Python package manager that handles Python versions automatically — no manual Python setup needed:

```sh
# Install uv: https://docs.astral.sh/uv/getting-started/installation/
uv tool install pre-commit --with pre-commit-uv
pre-commit install
```

The `--with pre-commit-uv` flag adds a plugin that patches pre-commit to use uv for installing Python-based hooks, which is much faster than the default behavior.

To upgrade pre-commit later:

```sh
uv tool upgrade pre-commit
```

To remove `pre-commit`, run `pre-commit uninstall`.

## How It Works

Once installed, `pre-commit` runs automatically before every `git commit`. If an issue is found, there are two possible outcomes:

1. The check initially fails and your staged changes are not committed, but `pre-commit` auto-fixes the problem. You'll see a new unstaged git change like this:

Add the auto-fixed change to staging and commit again. The check should now pass.

1. The check fails and your staged changes are not committed. You'll see an error message like this:


Fix the problem locally using the error message and/or guidance from the issue's lead, then re-commit.

> \[!NOTE]
> If you ever need to bypass the hook (e.g., for a work-in-progress commit), use `git commit --no-verify`. For more on `pre-commit`, see <https://pre-commit.com/>.

To manually run `pre-commit` against all files (e.g., before pushing), run `pre-commit run --all-files`.

## The GitHub CI Server

The CI server also runs `pre-commit` on every push. If you don't have `pre-commit` installed locally, your PR will fail checks and you'll need to fix issues after the fact — which means more waiting and more pushes. Install it locally to catch problems before they reach CI.

When a CI check fails, one of two things may happen:

1. The `pre-commit` bot pushes a new commit that auto-fixes the issue:

Pull in the bot's changes with `git pull origin HEAD` to avoid conflicts with future pushes.

1. The check simply fails and requires manual intervention:

Click "Details" to see what caused the failure, fix it locally, and push again. Reach out to the issue's lead if you're unsure how to proceed.

## Generating POT Files

If your commit involves adding, removing or altering text that will be visible to the user and is properly internationalized, an update of the translation template file will be automatically bundled in with your changes via `pre-commit`.

### What this means

* Your code will "fail" a test called `Generate POT`, give you the error message `Files were modified by this hook`, and add `messages.pot` changes to your git unstaged changes.
* All you need to do to "pass" the test is add the `messages.pot` file to staging and redo your commit; the `Generate POT` test should now pass, and your changes will be immediately available to translators once your branch is merged.

If you're not running `pre-commit` locally:

* The CI will push a new commit to your remote branch with the necessary `messages.pot` updates.
* Run `git pull origin HEAD` before making further changes to avoid conflicts.