Install & Compatibility
Where this runs
tested against v0.25 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.458s · 19.4MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 1.7s · import 0.398s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
api.Validator
✓ from validate_pyproject import api
Main class for programmatic validation.
errors.ValidationError
✓ from validate_pyproject import errors
Exception raised for validation failures.
cli.main
✓ from validate_pyproject import cli
Entry point for the command-line interface, typically not imported directly in user code but executed via `validate-pyproject` command.
This example demonstrates how to programmatically validate a `pyproject.toml` file content using `validate-pyproject`. It uses `tomli` to parse the TOML string into a Python dictionary, then instantiates `api.Validator` to perform the checks.
import tomli
from validate_pyproject import api, errors
import os
# Example pyproject.toml content
PYPROJECT_TOML_CONTENT = '''
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "my-package"
version = "1.0.0"
description = "A simple Python package"
requires-python = ">=3.8"
keywords = ["packaging", "example"]
classifiers = [
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
]
authors = [
{name = "Example Author", email = "author@example.com"},
]
maintainers = [
{name = "Example Maintainer", email = "maintainer@example.com"},
]
'''
# Parse the TOML string into a dictionary
pyproject_as_dict = tomli.loads(PYPROJECT_TOML_CONTENT)
# Instantiate the validator (can be configured with extra schemas or plugins)
validator = api.Validator()
try:
# Perform the validation
validator(pyproject_as_dict)
print("pyproject.toml is valid!")
except errors.ValidationError as ex:
print(f"Invalid pyproject.toml: {ex.message}")
# More detailed errors can be accessed via ex.details
for error in ex.details:
print(f" - {error.message} at {error.json_path}")
validate-pyproject --version
Errors
Common errors & fixes
validate_pyproject.errors.ValidationError: Invalid Document: ...
The `pyproject.toml` file contains data that does not conform to the expected JSON Schema for Python packaging metadata (e.g., missing required fields, incorrect types, invalid values).
fixReview the error message details (`ex.message`, `ex.details` if using the API) to identify the specific validation failure. Consult the official `pyproject.toml` specifications (PEPs like 621) or `validate-pyproject` documentation for schema requirements. Example: `[project]` table might be missing `name` or `version`.
ImportError: cannot import name 'tomli' from 'validate_pyproject.api' (or similar for other dependencies)
The `tomli` package (or `packaging`, `trove-classifiers`) is a conditional dependency for `validate-pyproject`'s full functionality. If you installed `validate-pyproject` without the `[all]` extra, these might be missing for Python versions that require them (e.g., `tomli` for Python < 3.11).
fixInstall `validate-pyproject` with the `[all]` extra: `pip install 'validate-pyproject[all]'`. This ensures all necessary optional dependencies are included for full validation capabilities.
validate-pyproject --help
... Command 'validate-pyproject' not found ...
The `validate-pyproject` CLI tool is not in your system's PATH, likely because it was installed into a virtual environment that isn't activated, or `pipx` was used without linking the executables globally.
fixEnsure your virtual environment is activated, or if installed via `pipx`, run `pipx ensurepath` to add pipx-managed executables to your PATH. Alternatively, you can run it directly: `python -m validate_pyproject.cli --help`.
Upgrade
Version history
0.25latest on PyPI · released Feb 2, 2026
Audit
Dependencies
tomlioptionalUsed for parsing TOML files (for Python < 3.11).
packagingoptionalUsed for validating aspects of PEP 621, required for full validation.
trove-classifiersoptionalUsed for validating project classifiers, can be bypassed by setting `NO_NETWORK` or `VALIDATE_PYPROJECT_NO_NETWORK` environment variables.
fastjsonschemarequiredUnderlying JSON Schema validation engine.