Supprt `pyproject.toml` based config

[Goldziher]

This issue is an offshot of #593.

I don't think much verbiage is required - basically, it would be great to have pyproject.toml support (with or without a special yaml config file). For Python-based projects, it's great. Especially monorepos.

[j178]

Could you give me a simple example of what you mean by “pyproject.toml support”? Are you thinking of a local Python hook that uses the local repo (with pyproject.toml) as a dependency?

[Goldziher]

No, I mean as an alternative to .pre-commit-config.yaml, a central place for configuration.

[ulgens]

I wouldn't say .pre-commit-config.yaml is the place for configuration, because it seems that configuration options are only available through environment variables. I think it's better to have the repo/hook setup in a .pre-commit-config.yaml file but I was expecting to be able to use these config options in pyproject.toml

[ulgens]

@j178 How does a "needs decision" process works for the project? Do we need to vote somehow? What is the question that needs the decision for?

[j178]

If I understand this request correctly, it’s asking for the ability to configure hooks in pyproject.toml under a tool.prek section.

The “needs decision” label basically means it’s waiting for more use cases or discussion before anything gets decided.

[ulgens]

it’s asking for the ability to configure hooks in pyproject.toml under a tool.prek section.

What if we say not hooks but the config options?

[j178]

What if we say not hooks but the config options?

That would be "needs decision" too :)

[lmmx]

• Continuing from Support prek.yaml ? #593 (that got side-tracked from the topic of YAML!)

For reference, here’s a list of reasons why pre-commit didn’t go TOML. Anthony gives this example of how things would look when using an unchanged structure to represent the same data.

Anthony raises a good point here

though pre-commit is written in python it is not a python-specific tool -- it does not make sense to add a pyproject.toml file to a non-python project

and in fact, now that prek is written in Rust, I feel like it should be mentioned that this would open up configuring prek in Cargo.toml not just pyproject.toml

Those comments were post-PEP 621 so pyproject TOMLs would have been in use (I honestly don’t remember precisely how fast the rollout went). Now in almost 2026 it’s much more common for tools to suggest config in central TOMLs.

For example, in Python land ruff and uv allow both standalone and pyproject TOML configuration

• ruff: https://docs.astral.sh/ruff/configuration/
• uv: https://docs.astral.sh/uv/concepts/configuration-files/

(I’ve actually never seen a uv.toml and find ruff.toml to be less portable, personally)

In Rust land, there are TOML files like taplo.toml and release-plz.toml, and many tools allow ‘tool’ section config in Cargo.toml.

…all that said I don’t initially find that TOML as written above very legible and suspect it would actually be detrimental to UX, in terms of the user’s ability to glance over it and see if all is correct… so I’m not sure how I feel about it.

My instinctive response is that surely we ought be writing them more like Rust dependencies

[tool.prek.repos]
mypy = { hooks = ["mypy"], repo = "https://github.com/pre-commit/mirrors-mypy", rev = "v1.17.1" }

Now that I like!

[lmmx]

I wouldn't say .pre-commit-config.yaml is the place for configuration, because it seems that configuration options are only available through environment variables. I think it's better to have the repo/hook setup in a .pre-commit-config.yaml file but I was expecting to be able to use these config options in pyproject.toml

I think this comment is perhaps going in a different direction (or I am unclear what the general request is).

My impression from #593 (which spawned this one) was people wanted to configure their hooks in pyproject.toml, not just the prek options that are currently set via env vars.

I think to get the former we would need to discuss this on the basis of essentially a port from pre-commit-config.yaml to prek.toml and then allowing that to alternatively be configured in a [tool.prek] pyproject.toml section or a [package.metadata.prek]/[workspace.metadata.prek] section in Cargo.toml (docs, docs).

The latter is a separate issue of obtaining values for things that are currently set only via env var (i.e. of adding rather than porting the ability to configure those things). Not saying that is a problem, just that it’s not what this discussion was about initially from my reading, that would need to be tackled in another way.

Note that in other issues, people talk about those env vars as being deliberately not set in the config YAML, emphasis added:

Proposal. For example OVERRIDE_PREK_ARGS_hook_name variable name could override the args for specific hook. That has a nice property that it would not have to be stored in the .pre-commit-config.yaml - it would just have to be defined in the CI, and you would not have to tie it to CI - or do auto-detection, simply setting the env var in CI would change the args.

Originally posted by potiuk in #836

[lmmx]

Pyproject TOML format

Also note the opposition to the suggestion in the title of this thread here by Paul Moore of CPython core:

The pyproject.toml format was designed for packaging configuration. While we included a reserved [tool] section for tool-specific configuration, there was no intention at the time to define a format that was capable of handling every possible type of configuration data.

While it’s certainly true that putting configuration in pyproject.toml has become far more popular than we expected, it’s hardly the fault of the format if it’s being pushed to its limits by certain projects. For example, there’s no reason pydoc-markdown couldn’t store its config in a YAML file if that format makes it easier to express the necessary configuration.

The earlier reference to the developer of flake8 is the same person who made pre-commit:

Some developers (eg. the author of flake8) have been reluctant to embrace pyproject.toml due to syntax issues which looked likely to be addressed in TOML 1.1. However unless something changes, it seems unlikely that TOML 1.1 will ever see the light of day given the lack of resources to go through the pending PRs.

Tool configuration scope

The thread also distinguishes "a first-class product in its own right" like documentation from genuine "configuration"

A table of contents for a doc site seems like it’s really stretching the idea of “configuration”.

So I think similarly there'd be a case that configuring prek can live in pyproject.toml but specifying hooks is arguably not configuration of behaviour. Tools like uv/ruff allow setting filters for lints but those lints are all already in the tool. prek on the other hand can be supplied with any URLs as a set of hooks, I'm not sure if it's "configuration" in the same way. The things we currently set as env vars or CLI flags would definitely be config.

Note this is exactly the issue touched on in my last comment: we should really distinguish hooks and configuration as separate things. The .pre-commit-config.yaml format combined the two:

• The main reference for .pre-commit-config.yaml calls the hooks "repository mappings" source
• (Not mentioned in the main reference) pre-commit.ci is configured in the ci: section source

I think I'd say that by definition the repository mappings are not configuration because they do not have a default, and if not set the tool will not do anything. Everything else on the other hand is optional and has a default, changing which will 'configure' the tool's behaviour.

In microservices frameworks like Serverless the functions key that defines deployed microservices (similarly to how we use hooks here) are called "infrastructure" (IaC or infrastructure-as-code) rather than purely config-as-code. The repos key in prek's YAML file provisions rather than configures.

[ulgens]

So I think similarly there'd be a case that configuring prek can live in pyproject.toml but specifying hooks is arguably not configuration of behaviour.

+1 for this take, but I don't think flooding the issue helps.

[lmmx]

+1 for this take, but I don't think flooding the issue helps.

No, this actually does help. This issue has been stuck as "needs decision" precisely because it hasn't been discussed, so I'm moving it along.

The problem is that there are two separate requests here:

• @Goldziher wants TOML instead of YAML for hooks
• @ulgens wants pyproject.toml support for options currently set via env vars.
  • Update Split off as Make env var options configurable via pyproject.toml #1175

These are different features, and conflating them is why this has stalled.

The precedents I cited suggest TOML may not be ideal for hook provisioning (the tool's product), but people want it and that's what this ticket was opened for.

To make this actionable: let's address configuration support (the env vars) separately, that's uncontroversial. Then we can decide whether to add hook provisioning to pyproject.toml once the configuration story is clear.