https://github.com/terror/pyproject
A linter and language server for `pyproject.toml` files
https://github.com/terror/pyproject
Last synced: 3 months ago
JSON representation
A linter and language server for `pyproject.toml` files
- Host: GitHub
- URL: https://github.com/terror/pyproject
- Owner: terror
- License: cc0-1.0
- Created: 2025-11-17T02:11:57.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2026-01-28T01:54:55.000Z (4 months ago)
- Last Synced: 2026-02-01T14:13:51.221Z (4 months ago)
- Language: Rust
- Size: 3.16 MB
- Stars: 10
- Watchers: 1
- Forks: 0
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING
- License: LICENSE
Awesome Lists containing this project
README
## pyproject
[](https://github.com/terror/pyproject/releases/latest)
[](https://github.com/terror/pyproject/actions/workflows/ci.yaml)
[](https://codecov.io/gh/terror/pyproject)
[](https://github.com/terror/pyproject/releases)
**pyproject** is a linter and language server for
[`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/)
files.
The
[`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/)
specification has become
[increasingly more complex](https://peps.python.org/pep-0725/) over time.
Although tools apply their own validation rules, there is no standard way to
surface useful configuration errors/warnings directly in an editor before those
tools run. This language server (and linter) provides real-time feedback on
configuration issues as you edit your project file, helping you catch errors
early and maintain clearer, more reliable builds.
We currently provide over
[30+ rules](https://github.com/terror/pyproject/tree/master/src/rule) that cover
syntax validation, schema compliance, project metadata (i.e. name, version,
description, etc), dependencies (i.e. PEP 508 format, version bounds,
deprecations, updates), and lots more. The rule system is designed to be easily
extended with custom rules to fit any projects specific needs.
## Installation
`pyproject` should run on any system, including Linux, MacOS, and the BSDs.
The easiest way to install it is by using
[cargo](https://doc.rust-lang.org/cargo/index.html), the Rust package manager:
```bash
cargo install pyproject
```
Otherwise, see below for the complete package list:
#### Cross-platform
Package Manager
Package
Command
Cargo
pyproject
cargo install pyproject
Homebrew
terror/tap/pyproject
brew install terror/tap/pyproject
Pip
pyproject
pip install pyproject
**n.b.** Since we publish a release to [PyPI](https://pypi.org/), tools like
[uv](https://docs.astral.sh/uv/) work right out of the box, i.e.
`uvx pyproject check` should just work with sensible default rules.
### Pre-built binaries
Pre-built binaries for Linux, MacOS, and Windows can be found on
[the releases page](https://github.com/terror/pyproject/releases).
## Usage
`pyproject` can be used from the command-line or as a language server.
### CLI
Below is the output of `pyproject --help`:
```present cargo run -- --help
pyproject 0.1.2
Usage: pyproject
Commands:
check Check a pyproject.toml file for errors and warnings [aliases: lint]
format Format a pyproject.toml file [aliases: fmt]
server Start the language server [aliases: lsp]
Options:
-h, --help Print help
-V, --version Print version
```
**n.b.** Running `pyproject check` or `pyproject format` on their own will
attempt to perform actions on the nearest `pyproject.toml` file, walking
backwards from the current location.
## Configuration
You can configure rules in your `pyproject.toml` under the `[tool.pyproject]`
section.
Each rule can be set to a severity level (`error`, `warning`, `hint`,
`information` (or `info`), or `off`) using either a simple string or a table
with a `level` field:
```toml
[tool.pyproject.rules]
project-unknown-keys = "warning"
project-dependency-updates = { level = "hint" }
project-requires-python-upper-bound = "off"
```
Rule identifiers are shown in diagnostic output (e.g.,
`error[project-unknown-keys]`). Rules that aren't explicitly configured use
their default severity level.
## Prior Art
This project was inspired by a language server I saw for
[`Cargo.toml`](https://doc.rust-lang.org/cargo/reference/manifest.html) files,
namely [crates-lsp](https://github.com/MathiasPius/crates-lsp). I couldn't find
similar a tool for
[`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/)
files, so I thought I'd write one.