---
title: "pre-commit hooks"
draft: false
type: docs
layout: single

menu:
  docs:
    weight: 120
---

# pre-commit hooks

pre-commit is a framework for building and running
[git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks).
See the official documentation for more information: [pre-commit.com](https://pre-commit.com/)

This document provides a list of available pre-commit hooks provided by Poetry.


{{% note %}}
If you specify the `args:` for a hook in your `.pre-commit-config.yaml`,
the defaults are overwritten. You must fully specify all arguments for
your hook if you make use of `args:`.
{{% /note %}}

{{% note %}}
If the `pyproject.toml` file is not in the root directory, you can specify `args: ["-C", "./subdirectory"]`.
{{% /note %}}

## poetry-check

The `poetry-check` hook calls the `poetry check` command
to make sure the poetry configuration does not get committed in a broken state.

### Arguments

The hook takes the same arguments as the poetry command.
For more information see the [check command]({{< relref "cli#check" >}}).

## poetry-lock

The `poetry-lock` hook calls the `poetry lock` command
to make sure the lock file is up-to-date when committing changes.

### Arguments

The hook takes the same arguments as the poetry command.
For more information see the [lock command]({{< relref "cli#lock" >}}).

## poetry-export

The `poetry-export` hook calls the `poetry export` command
to sync your `requirements.txt` file with your current dependencies.

{{% warning %}}
This hook is provided by the [Export Poetry Plugin](https://github.com/python-poetry/poetry-plugin-export).
{{% /warning %}}

{{% note %}}
It is recommended to run the [`poetry-lock`](#poetry-lock) hook or [`poetry-check`](#poetry-check) with argument `--lock` prior to this one.
{{% /note %}}

### Arguments

The hook takes the same arguments as the poetry command.
For more information, see the [export command]({{< relref "cli#export" >}}).

The default arguments are `args: ["-f", "requirements.txt", "-o", "requirements.txt"]`,
which will create/update the `requirements.txt` file in the current working directory.

You may add `verbose: true` in your `.pre-commit-config.yaml` in order to output to the
console:

```yaml
hooks:
-   id: poetry-export
    args: ["-f", "requirements.txt"]
    verbose: true
```

Also, `--dev` can be added to `args` to write dev-dependencies to `requirements.txt`:

```yaml
hooks:
-   id: poetry-export
    args: ["--dev", "-f", "requirements.txt", "-o", "requirements.txt"]
```

## poetry-install

The `poetry-install` hook calls the `poetry install` command to make sure all locked packages are installed.
In order to install this hook, you either need to specify `default_install_hook_types`, or you have
to install it via `pre-commit install --install-hooks -t post-checkout -t post-merge`.

### Arguments

The hook takes the same arguments as the poetry command.
For more information, see the [install command]({{< relref "cli#install" >}}).

## Usage

For more information on how to use pre-commit, please see the [official documentation](https://pre-commit.com/).

A minimalistic `.pre-commit-config.yaml` example:

```yaml
repos:
-   repo: https://github.com/python-poetry/poetry
    rev: ''  # add version here
    hooks:
    -   id: poetry-check
    -   id: poetry-lock
    -   id: poetry-export
    -   id: poetry-install
```

A `.pre-commit-config.yaml` example for a monorepo setup or if the `pyproject.toml` file is not in the root directory:

```yaml
repos:
-   repo: https://github.com/python-poetry/poetry
    rev: ''  # add version here
    hooks:
    -   id: poetry-check
        args: ["-C", "./subdirectory"]
    -   id: poetry-lock
        args: ["-C", "./subdirectory"]
    -   id: poetry-export
        args: ["-C", "./subdirectory", "-f", "requirements.txt", "-o", "./subdirectory/requirements.txt"]
    -   id: poetry-install
        args: ["-C", "./subdirectory"]
```

## FAQ

### Why does `pre-commit autoupdate` not update to the latest version?

`pre-commit autoupdate` updates the `rev` for each repository defined in your `.pre-commit-config.yaml`
to the latest available tag in the default branch.

Poetry follows a branching strategy where the default branch is the active development branch,
and fixes get backported to stable branches. New tags are assigned in these stable branches.

`pre-commit` does not support such a branching strategy and has decided to not implement
an option, either on the [user's side](https://github.com/pre-commit/pre-commit/issues/2512)
or the [hook author's side](https://github.com/pre-commit/pre-commit/issues/2508), to define a branch for looking
up the latest available tag.

Thus, `pre-commit autoupdate` is not usable for the hooks described here.

You can avoid changing the `rev` to an unexpected value by using the `--repo` parameter (may be specified multiple
times), to explicitly list repositories that should be updated. An option to explicitly exclude
repositories [will not be implemented](https://github.com/pre-commit/pre-commit/issues/1959) into `pre-commit`.

### Are there any alternatives to `pre-commit autoupdate`?

You may use [pre-commit-update](https://pypi.org/project/pre-commit-update/) as an alternative to
`pre-commit autoupdate`.

Since `pre-commit-update` can be used as a pre-commit hook itself, the easiest way
to make use of it would be to include it inside `.pre-commit-config.yaml`:

```yaml
repos:
-   repo: https://gitlab.com/vojko.pribudic.foss/pre-commit-update
    rev: v0.5.1post1
    hooks:
    -   id: pre-commit-update
-   repo: https://github.com/python-poetry/poetry
    rev: 1.8.3
    hooks:
    -   id: poetry-check
    -   id: poetry-lock
    -   id: poetry-export
    -   id: poetry-install
```

Your `.pre-commit-config.yaml` repos will be checked and updated every time pre-commit hooks run.

For more advanced configuration, please check the `pre-commit-update` documentation.
