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.

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:

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 for Linux, MacOS, and Windows can be found on the releases page.

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

Below is the output of pyproject --help:

pyproject 0.1.2

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.

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.

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.