Setting the target python version - confusion around PYO3_PYTHON and --interpreter parameter

[dantliff-sqc]

I'm building a Python extension as a wheel and I want to target Python 3.10, although I have Python 3.12 installed on the build host, on Linux (Ubuntu 24.04). I'm not using ABI3. I'm using PyO3 v0.24.0 with pyo3 bindings, the generate-import-lib feature, and crate-type = ["cdylib"].

Off the bat, maturin targets Python 3.12:

$ maturin --version
maturin 1.7.0

^^^ I'm stuck with this version for now, for elaborate reasons

$ python --version
Python 3.12.3

$ PYO3_PRINT_CONFIG=1 maturin build
...
🐍 Found CPython 3.12 at [...]/venv/bin/python
...
  implementation=CPython
  version=3.12
  shared=true
  abi3=false
  lib_name=python3.12
  lib_dir=[...]/3.12.3/lib
  executable=[...]/venv/bin/python
  pointer_width=64
  build_flags=
  python_framework_prefix=
  suppress_build_script_link_lines=false

So that seems to have picked up Python 3.12, and if I remove PYO3_PRINT_CONFIG then it creates -cp312-cp312-linux_x86_64.whl, as expected.

According to Configuring the Python version, I should be able to set PYO3_PYTHON=python3.10, to change the wheel target version, however:

$ PYO3_PRINT_CONFIG=1 PYO3_PYTHON=python3.10 maturin build
...
🐍 Found CPython 3.12 at [...]/venv/bin/python
...
  implementation=CPython
  version=3.12
...

$ PYO3_PYTHON=python3.10 maturin build
📦 Built wheel for CPython 3.12 to [...]-cp312-cp312-linux_x86_64.whl

It seemed to have had no effect.

There's a parameter to maturin called --interpreter which has very little documentation (that I can find). The best I can find is:

$ maturin build --help
...
  -i, --interpreter [<INTERPRETER>...]
          The python versions to build wheels for, given as the executables of interpreters
          such as `python3.9` or `/usr/bin/python3.8`
...

This option is not mentioned in Building and distribution at all, and only briefly mentioned in maturin docs as well, with no additional information.

However, it seems to be necessary in this case:

$ PYO3_PRINT_CONFIG=1 maturin build --interpreter python3.10
...
⚠️  Warning: Failed to determine python platform
⚠️  Warning: skipped unavailable python interpreter 'python3.10' from pyenv
🐍 Found CPython 3.10
...
  implementation=CPython
  version=3.10
  shared=true
  abi3=false
  pointer_width=64
  build_flags=WITH_THREAD
  suppress_build_script_link_lines=false

$ maturin build --interpreter python3.10
...
📦 Built wheel for CPython 3.10 to [...]-cp310-cp310-linux_x86_64.whl

I can then take that -cp310- wheel and copy it to a Linux machine with Python 3.10 and it works, whereas the -cp312- one wouldn't because pip under 3.10 would reject it as incompatible.

What I'm really not clear about is whether this is working as intended. There's so little documentation about this --interpreter option, and PYO3_PYTHON=python3.10 seems to have no effect, that I'm not sure I'm going about this the right way.

In what cases would PYO3_PYTHON=python3.10 work? Does python3.10 need to be in the PATH?