Technology · PRACTICAL GUIDE
Poetry uses the wrong Python? Prove the interpreter and environment before replacing it
Compare the shell executable, Poetry’s project environment and the runtime’s sys.executable, prefix and base_prefix. Then audit the project constraint and Poetry configuration before choosing the narrowest repair.
A Python prompt can look correct while Poetry still selects a cached, activated or installation-time interpreter. The safe fix is to prove each path first, then change only the layer that is wrong.
Freeze the mismatch before changing anything
Do not delete .venv or run poetry env use on the first guess. From the project directory, record the shell command that resolves Python, the Poetry environment path and executable, and the runtime evidence inside poetry run. A compact evidence set is: command -v python (or Get-Command python on PowerShell), python -c "import sys; print(sys.executable); print(sys.prefix); print(sys.base_prefix)", poetry env info --path, poetry env info --executable, and poetry run python -c with the same sys fields. If the paths differ, the output already tells you whether the mismatch belongs to the shell, Poetry’s selected environment or the process launched by Poetry.
Read the three paths as different evidence
The shell’s python answers which executable PATH resolves. poetry env info --executable answers which interpreter Poetry associates with this project. sys.executable answers what the running process actually started, while sys.prefix and sys.base_prefix show whether that process is inside a virtual environment and which base installation created it. Python’s documentation warns that VIRTUAL_ENV is not definitive because a virtual environment can be used without activation. Treat the prompt name and VIRTUAL_ENV as hints, not proof.
Check the project constraint before selecting an interpreter
Read the project’s requires-python or Poetry Python constraint before changing the environment. Poetry requires an accessible interpreter that satisfies the declared range; it does not automatically install every required Python version. Compare the candidate interpreter’s exact version with the project constraint. A compatible path can then be selected explicitly with poetry env use /full/path/to/python or an available version such as poetry env use 3.12. If no installed interpreter satisfies the range, install or expose one through your normal platform tooling first; changing only the lock file or activation prompt cannot create it.
Audit configuration scope and an already existing environment
Configuration can make a correct shell look wrong. Check poetry config --list and the effective values of virtualenvs.create, virtualenvs.in-project, virtualenvs.path and virtualenvs.use-poetry-python, including environment variables in CI. With virtualenvs.create=false, Poetry may use the system environment when no active or stored project environment is found. With an existing cached environment, turning on in-project does not automatically migrate it to .venv. Record the old path before removing anything so you can distinguish a configuration change from an environment replacement.
Choose the narrowest repair for the proven branch
If only the shell path is wrong, fix shell or version-manager selection and re-run the evidence set. If Poetry is bound to the wrong project environment, use poetry env use with the verified interpreter and let Poetry create or select the matching environment. If an activated external environment is intentional, remember that Poetry will not create another environment while it detects the active one. If CI differs from local runs, compare the runner’s PATH, activated environment, Poetry configuration variables and the output of poetry run rather than copying a local cache path into automation.
Verify the repair and keep a rollback record
Repeat the same commands after the change. The Poetry environment executable and poetry run sys.executable should now resolve to the intended environment; sys.prefix should identify that environment, and sys.base_prefix should identify its base interpreter. Run the smallest project command that previously failed, then poetry check and the project’s tests. Keep the before-and-after paths and the configuration value you changed. If the new environment behaves worse, the evidence identifies the prior environment and prevents a blind cycle of deleting caches.
