poetry-check

Check validation and consistency between pyproject.toml and poetry.lock for Poetry

$ poetry check

$ poetry check --lock

$ poetry check --strict

poetry check [--strict] [--help] [--quiet] [--verbose|-v] [--version] [--no-interaction]

--strict
    Returns a non-zero exit code for warnings, in addition to errors. Without this option, warnings might be printed, but the command could still exit with code 0 if no errors are found.

--help
    Displays help information about the check command.

--quiet
    Suppresses all command output, only returning an exit code.

--verbose (or -v, -vv, -vvv)
    Increases the verbosity of messages. Multiple -v options increase the level of detail.

--version
    Displays the current Poetry application version.

--no-interaction
    Do not ask any interactive questions.

The poetry check command is an essential tool for maintaining the integrity and correctness of a Python project managed by Poetry. Its primary function is to validate the pyproject.toml file against established standards and Poetry's specific schema.

This includes verifying the syntax and structure of project metadata, dependencies, scripts, and other configuration settings defined within the file. By running poetry check, developers can proactively identify and correct potential issues such as malformed entries, missing required fields, or non-compliant dependency specifications (e.g., against PEP 508 or PEP 621).

This early detection prevents more significant problems during dependency installation (poetry install), package publishing, or when other developers attempt to work with the project. It provides a quick and static analysis of the project configuration without attempting to resolve or install any dependencies, making it a fast and reliable first line of defense for project health.

While poetry check is excellent for validating the pyproject.toml file's syntax and schema, it does not perform runtime checks or dependency resolution. It will not verify if specified packages actually exist in the configured repositories, or if their versions are compatible with each other. For such checks, commands like poetry install or poetry update are necessary, as they attempt to resolve and fetch dependencies.

The poetry check command exits with status 0 if the pyproject.toml file is valid and no errors or warnings (when --strict is used) are encountered. It exits with a non-zero status (typically 1) if any errors are found, or if warnings are present and the --strict flag is enabled. This makes it suitable for use in continuous integration (CI) pipelines to ensure project integrity before deployment or further build steps.

The Poetry project, including the poetry check command, was initiated by Sébastien Eustace with its first public releases around late 2017 and early 2018. From its inception, the command-line interface (CLI) was designed to prioritize ease of use and project integrity. The check command has been a foundational part of Poetry's toolkit, embedded in its CLI from very early versions, reflecting the critical importance of validating the pyproject.toml configuration file before any other dependency management operations are performed. Its purpose has remained consistent: to ensure the core project configuration is sound and compliant.

poetry install(1), poetry update(1), poetry lock(1), pip(1), pipenv(1)