poetry-debug

Show debug info about Poetry and your project's virtual environment

$ poetry debug info

$ poetry debug resolve

$ poetry debug tags

poetry debug subcommand [subcommand_options]

subcommand
    The specific debug operation to perform, such as info for environment details or resolve for dependency resolution troubleshooting.

--show-directory
    (For info subcommand)
Displays the root directory of the current Poetry project.

--extras
    (For resolve subcommand)
A comma-separated list of extras to enable during the dependency resolution process.

--python
    (For resolve subcommand)
The specific Python version to use when attempting dependency resolution.

--dry-run
    (For resolve subcommand)
Executes the resolution process without actually modifying any files, showing what would happen.

--only-lock
    (For resolve subcommand)
Forces the resolver to only use the lock file, ignoring potentially newer constraints in pyproject.toml.

-v, --verbose
    Increases the verbosity of messages during command execution, providing more detailed output for debugging.

The poetry debug command serves as a critical diagnostic tool within the Poetry dependency management ecosystem. Unlike a standalone executable, it acts as a parent namespace for various subcommands designed to help users troubleshoot issues related to project configuration, virtual environment setup, and most importantly, dependency resolution. This command is invaluable for developers encountering complex dependency conflicts, unexpected installation behavior, or general issues with their project's dependencies. Its primary subcommands, info and resolve, offer deep insights into the current environment and the intricate process of dependency graph construction, enabling users to quickly identify the root causes of problems and find solutions. It bridges the gap between a problem and its resolution by providing clear, actionable diagnostic data.

The poetry debug command is not a standalone executable. It requires Poetry to be installed and accessible in your shell's PATH. It functions as a collection of subcommands, and invoking poetry debug without a specific subcommand will display general help information rather than performing any particular debugging task. Its utility is entirely dependent on the specific subcommand invoked (e.g., info or resolve).

info:
Displays detailed information about the current Poetry environment, including Poetry's version, Python version, virtual environment path, project root, and other relevant system details. This is often the first step in diagnosing environment-related issues.

resolve:
Helps troubleshoot dependency resolution problems. It attempts to resolve the project's dependencies and provides verbose output about the resolution process, including why certain packages were chosen or rejected. This subcommand is invaluable for understanding conflicts or unexpected dependency versions.

The debug namespace was introduced to Poetry as the project matured, recognizing the need for better introspection and diagnostic tools. As dependency graphs grew more complex and users encountered varied environment configurations, the demand for clear debugging information became paramount. The info subcommand was one of the earlier additions, providing a snapshot of the environment. The resolve subcommand, especially its detailed output, became crucial for understanding the intricate process of dependency resolution, evolving to help users pinpoint conflicts that were otherwise obscure. Its development reflects Poetry's commitment to user experience and robust dependency management.

poetry(1), pip(1), python(1), pip-tools(1)