pyproject 1!0.2.1

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

pyproject

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

pyproject brings real-time feedback to your pyproject.toml files, including:

• Syntax validation and schema compliance for project and tool configuration.

• Over 30 built-in rules for project metadata and dependencies, including PEP 508 validation, version bounds, deprecations, and available updates.

• Diagnostics directly in your editor, so configuration errors are caught before the tools that consume your project file run.

If you need help with pyproject please feel free to open an issue. Feature requests and bug reports are always welcome!

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.2.1

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.

Language Server

Start the language server with pyproject server or pyproject lsp. The server communicates over standard input and output and provides diagnostics, completions, hover descriptions, and formatting for pyproject.toml files.

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.