Troubleshooting & FAQ

Why: unlike pip, which resolves for the one interpreter it runs on, Poetry locks for every Python in requires-python. Here >=3.9 includes 3.9 and 3.10, for which no matching numpy exists. Fixes:

The same problem appears with an upper bound: requires-python = ">=3.10,<4.0" (a translated ^3.10) cannot be satisfied by a package that declares <3.14.

Source: Poetry FAQ: supported Python range is not compatible.

With -v, the traceback shows the exception behind the message: SolverProblemError, raised from the resolver’s SolveFailureError (the strings come from src/poetry/mixology/failure.py). Read the last line first: it names the two direct requirements that cannot both hold. The lines above it are the proof, release by release. Fix one of the two constraints; poetry show --why and poetry show --tree --why <package> show who requires what in a working project. Nothing is written: poetry add leaves pyproject.toml and poetry.lock unchanged when resolution fails (exit code 1).

Source: Poetry CLI: show, Poetry: Version constraints.

Poetry needs the metadata of many candidate releases for every platform. Where an index offers no PEP 658 metadata or the JSON API has none, it downloads the files to read it, which costs time and bandwidth. The FAQ’s advice: constrain the package Poetry is downloading many versions of more narrowly. Keep solver.lazy-wheel = true (the default), and keep the cache: the second resolution is much faster. -vvv shows which package is being fetched.

Source: Poetry FAQ: Why is the dependency resolution process slow?.

poetry update stays inside the constraint in pyproject.toml. With attrs (>=25,<26) locked at 25.4.0 and 26.1.0 released:

poetry show --outdated lists attrs 25.4.0 26.1.0. Widen the constraint, or poetry add attrs@latest. (Since 2.4, a name that is not a dependency at all is an error instead of being ignored.)

Source: Poetry CLI: update, Poetry CLI: add, Poetry: Using the @ operator.

poetry add writes ^1.2-style constraints, that is with an upper bound. The FAQ’s answer: for an application, an upper bound protects against a future major release; for a library used by other packages, upper bounds cause needless conflicts for your users, so prefer >= unless you know the next release breaks you. See Versions & Dependency Specifiers.

Source: Poetry FAQ: Are unbound version constraints a bad idea?.

Why: the content-hash in poetry.lock no longer matches the dependency-relevant parts of pyproject.toml (here a dependency was added by hand). Since 1.8 this is an error, not a warning. Fix: poetry lock (it keeps every other locked version), review the diff, commit both files together. In CI, fail early with poetry check --lock instead of locking there. After a merge conflict in poetry.lock, resolve pyproject.toml first, take either side of the lock file and run poetry lock to rebuild it.

Source: Poetry CLI: lock, Poetry CLI: check.

A lock file written by a newer Poetry gives The lock file might not be compatible with the current version of Poetry. (newer format, same major) or The lock file is not compatible with the current version of Poetry. (unknown major format). Upgrade Poetry, or pin the team’s Poetry with requires-poetry; see Versions & Release History.

Poetry starts from the python on PATH, then looks for another interpreter that satisfies requires-python. Install one (or let Poetry do it with the experimental poetry python install 3.15) and select it with poetry env use 3.15. See Managing Environments.

Source: Poetry: Switching between environments, Poetry CLI: python install.

If a virtual environment is active (VIRTUAL_ENV is set, for example by tox, nox or your shell), Poetry uses it instead of its own. poetry env info -p shows which one is in use. Deactivate the other environment, or use poetry run from a clean shell. With virtualenvs.create = false, Poetry installs into whatever interpreter runs it; since 2.5.0 it at least fails with an error when that interpreter does not satisfy the project.

The setting applies when an environment is created. A project that already has an environment in the cache keeps using it; poetry env remove --all, then poetry install, creates .venv.

poetry shell and poetry export are plugins since 2.0, and poetry run <cmd> reports Command not found: <cmd> when the command is not installed in the environment. The replacements are on Migrating to Poetry 2.