[Python] How do I properly integrate tox in my poetry project?

Hello I have a poetry project but I'd like to learn how to use tools like tox to test my project against different versions of python

here is my complete toml file

[tool.poetry]
name = "projectname"
version = "0.1.0"
description = "my package"
authors = ["Name Name <email@gmail.com>"]
readme = "README.md"
packages = [{ include = "mypackage", from = "src" }]

[tool.poetry.dependencies]
python = "^3.10"
beautifulsoup4 = "^4.13.3"
rapidfuzz = "^3.12.2"
requests = "^2.32.3"

[tool.poetry.group.dev.dependencies]
pytest = "^8.3.5"
pytest-benchmark = "*"
pytest-cov = "*"
ruff = "*"
pyright = "*"
pre-commit = "*"
tox = "^4.24.2"

[tool.poetry.scripts]
myscript = "mypackage.search_offers:main"

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

[tool.pytest.ini_options]
pythonpath = ["src"]
testpaths = ["tests"]

[tool.ruff]
line-length = 100 # Matches `black`
target-version = "py310" # Python version

[tool.ruff.lint]
extend-select = ["E", "F", "W", "I"] # Enable linting + import sorting
fixable = ["ALL"] # Auto-fix everything

[tool.ruff.format]
quote-style = "double" # Optional: use double quotes

[tool.pyright]
include = ["src", "tests"]
pythonVersion = "3.10"
typeCheckingMode = "strict"
reportMissingTypeStubs = false


[tool.tox]
env_list = ["py310", "py311", "lint", "type"]

[tool.tox.env.py310]
description = "Run tests with pytest on Python 3.10"
package = "editable" # ✅ Install local package in editable mode (like `pip install -e .`)
wheel_build_env = "build"
deps = ["pytest", "pytest-cov", "pytest-benchmark"]
commands = [["pytest", "--cov=src", "--cov-report=xml"]]

[tool.tox.env.py311]
description = "Run tests with pytest on Python 3.11"
package = "editable"
wheel_build_env = "build"
deps = ["pytest", "pytest-cov", "pytest-benchmark"]
commands = [["pytest", "--cov=src", "--cov-report=xml"]]

[tool.tox.env.lint]
description = "Run Ruff for linting"
skip_install = true
deps = ["ruff"]
commands = ["ruff check ."]

[tool.tox.env.type]
description = "Run Pyright for type checking"
skip_install = true
deps = ["pyright"]
commands = ["pyright"]




Running tox -e py310 and poetry run tox -e py310 works.

Running tox -e py311 or poetry run tox -e py311 will fail with error

py311: skipped because could not find python interpreter with spec(s): py311
py311: SKIP (0.01 seconds)
evaluation failed (0.06 seconds)


Here is what I did : I installed pyenv

brew install pyenv


Then I installed python 3.11

pyenv install 3.11


Following pyenv README.md documentation regarding usage with tox I set the new version as global system

pyenv global system 3.11.11


Here are the outputs of some commands :

> python3.11
zsh: command not found: python3.11
> pyenv which python3.11
/Users/myname/.pyenv/versions/3.11.11/bin/python3.11
> pyenv versions
system
* 3.11.11 (set by /Users/myname/Documents/myproject/.python-version)
> python --version
Python 3.10.10


Chatgpt tells me to add this line to the [tool.tox.env.py311] section in the toml.

basepython = ["/Users/myname/.pyenv/versions/3.11.11/bin/python3.11"] # ✅ Explicit Python path


It does solve the problem but I don't like this solution, i'd rather something that doesn't rely on manual input of the python path. I also intend to add this as a github action so I need something that doesn't rely on my machine settings

Can someone tell me if I messed up something ? Do I misunderstand how to use those tools ? I'm trying to learn tox and poetry so it's still very new to me

Thanks a lot in advance

Continue reading...