Poetry ignores the Python version specified in the pyproject.toml file

[acdha]

Description

Poetry uses the version of Python which was used to install Poetry no matter what the pyproject.toml file is configured to use.

Workarounds

poetry env use <VERSION> can be used to create the appropriate version environment first. Since Python 3.13 was just released, this breaks many previously-working configurations.

$ cd (mktemp -d)
$ /var/folders/hs/qvpck5vn/T/tmp.LsjrcWOb39> poetry init --python=3.12 -n
$ /var/folders/hs/qvpck5vn/T/tmp.LsjrcWOb39> python3.12 --version
Python 3.12.7
$ /var/folders/hs/qvpck5vn/T/tmp.LsjrcWOb39> poetry install
The currently activated Python version 3.13.0 is not supported by the project (3.12).
Trying to find and use a compatible version. 

Poetry was unable to find a compatible version. If you have one, you can explicitly use it via the "env use" command.

Poetry Installation Method

system package manager (eg: dnf, apt etc.)

Operating System

macOS

Poetry Version

Poetry (version 1.8.4)

Poetry Configuration

N/A

Python Sysconfig

N/A

Example pyproject.toml

[tool.poetry]
name = "tmp-lsjrcwob39"
version = "0.1.0"
description = ""
authors = ["Chris Adams <[email protected]>"]
readme = "README.md"
packages = [{include = "tmp"}]

[tool.poetry.dependencies]
python = "3.12"


[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Poetry Runtime Logs

N/A

[dimbleby]

python = "3.12" means "exactly version 3.12.0".

I guess that's not what you meant, but it is what you asked for and poetry is behaving correctly.

[acdha]

So that’s probably a usability issue since it should be consistent with poetry env use but that was just my reduction for this. My real projects had values like ^3.12.5.

Basically in either case I’d expect it to either use the specified version or fail, not to use the version Poetry was compiled with. I noticed this because it broke a large number of projects due to a common dependency which doesn’t yet support 3.13.

[dimbleby]

I can't tell what you are reporting, all I know is that you are now telling us that it is something different than what you reported.

I’d expect it to either use the specified version or fail

But it is failing, right? Or is what you showed not what you are trying to show?

[acdha]

There are two issues: one is that the poetry init --python has an undocumented inconsistency with poetry env use, where the latter will accept things like 3.11 and use the point version of python3.11 which is in the path.

The original one is simply that while the documentation says that things like python = "^3.7" will work, in practice that caret matching doesn't work the way you'd expect:

cadams@ /var/folders/hs/qvpck5vn/T/tmp.ytfDY1nsxc> poetry init --python="^3.9.0" -n
cadams@ /var/folders/hs/qvpck5vn/T/tmp.e25AD4Ky3O> grep python pyproject.toml
python = "^3.9.0"
cadams@ /var/folders/hs/qvpck5vn/T/tmp.ytfDY1nsxc> poetry install
Creating virtualenv tmp-ytfdy1nsxc-JtgGK1RE-py3.13 in /Users/cadams/Library/Caches/pypoetry/virtualenvs

If I use poetry env use 3.9 or poetry env use ^3.9.0, it correctly finds Python 3.9.20.

If I use the standard Python version specifiers from PEP-440 like ~=3.9.0 or >=3.9.0 <3.10, this does work as expected:

cadams@ /var/folders/hs/qvpck5vn/T/tmp.CzPT8laB7C> poetry init --python=">=3.9.0 <3.10" -n
cadams@  /var/folders/hs/qvpck5vn/T/tmp.CzPT8laB7C> poetry install
The currently activated Python version 3.13.0 is not supported by the project (>=3.9.0 <3.10).
Trying to find and use a compatible version. 
Using python3.9 (3.9.20)

[finswimmer]

Hey @acdha,

There are two issues: one is that the poetry init --python has an undocumented inconsistency with poetry env use, where the latter will accept things like 3.11 and use the point version of python3.11 which is in the path.

improvements to the docs are always welcome. For me the difference is stated out:

poetry init --help shows:

--python=PYTHON                  Compatible Python versions.

and poetry env use --help shows:

  python                     The python executable to use.

So the first is talking about versions and the later about the executable.

If you find that we can make it more clear, feel free to submit a PR 😃

fin swimmer

[acdha]

So the first is talking about versions and the later about the executable.

The first part is correct but the second is misleading because it technically accepts both. As written, you'd think you'd need to use it like poetry env use /usr/bin/python3.11, which is how other tools described that way work, but specifying a version like poetry env use 3.12 or poetry env use 3.12.7 also work. Ideally this would be documented like uv's python options and available in both places.