python-poetry
Poetry ignores the Python version specified in the pyproject.toml file
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
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.
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.
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?
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)
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 :smiley:
fin swimmer
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.
I can confirm this. I installed poetry with 3.13, but my project uses 3.11 (stated in the toml). When I do
poetry install it will create an environment with 3.13, ignoring the 3.11 in the toml
+1 that this can be a confusing user experience
It seems that if .python-version is present, poetry will aim to use that specific version, but it won't read from pyproject.toml
I often hit this point when I poetry env activate to start up a new virtual environment, then poetry install only to find that there is some conflict between the python version specified in the toml and the one used to set up the virtual environment. I'd even appreciate a simple warning, on virtual environment creation, about the incompatible versions.
There've been some more semi-documented changes and it's possible to get Poetry to in some cases do the right thing by changing your pyproject.toml file to use [project] section with requires-python AND setting the same version in [tool.poetry.dependencies].
[project]
…
requires-python = ">=3.12.5,<3.13"
[tool.poetry.dependencies]
python = ">=3.12.5,<3.13"
With that change commands like poetry install appears to work without requiring you to first run poetry env use 3.12 when Poetry itself is using 3.13, etc.
Poetry 1.8 just ignores project.requires-python. For Poetry 2, specifying exactly the same constraint for project.requires-python and tool.poetry.dependencies.python is redundant. See https://python-poetry.org/docs/pyproject/#requires-python for example.
If you have not set a specific version for the project with poetry env use before, Poetry 2 will try to find a suitable version. (Poetry 1.8 just fails.)
For Poetry 2, specifying exactly the same constraint for
project.requires-pythonandtool.poetry.dependencies.pythonis redundant. See https://python-poetry.org/docs/pyproject/#requires-python for example.
I’m aware of the documentation, which is why I was surprised to find that the actual code works the way I described. I updated my projects to Poetry 2.1.3 over the last few months and without specifying the version in both places it floated up to the version of Python used to run Poetry itself.
without specifying the version in both places it floated up to the version of Python used to run Poetry itself.
It works for me if I only specify project.requires-python. Can you provide a docker example?