pyproject 1!0.1.2

A linter and language server for `pyproject.toml` files

pyproject

pyproject is a linter and language server for pyproject.toml files.

The pyproject.toml specification has become increasingly more complex 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 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, the Rust package manager:

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, tools like 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.

Usage

pyproject can be used from the command-line or as a language server.

CLI

Below is the output of pyproject --help:

pyproject 0.1.0

Usage: pyproject <COMMAND>

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:

[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 files, namely crates-lsp. I couldn't find similar a tool for pyproject.toml files, so I thought I'd write one.