Managing Python Versions

Running the full tox test matrix requires multiple Python versions to be available on the local system. This project currently tests against:

Python 3.10

Python 3.11

Python 3.12

Python 3.13

The recommended and supported way to manage multiple Python versions is to use pyenv.

Why pyenv?

The built-in venv module can only create virtual environments from an already-installed Python interpreter. It cannot install or manage multiple Python versions.

pyenv allows multiple Python interpreters to be installed side by side and selected on a per-project basis. tox then uses these interpreters to automatically create isolated virtual environments.

macOS (OS X)

Installing pyenv

Install pyenv using Homebrew:

brew install pyenv

Add the following to your shell configuration file (e.g. ~/.zshrc or ~/.bashrc):

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

Restart your shell and verify the installation:

pyenv --version

Installing Python Versions

Install the required Python versions:

pyenv install 3.10.14
pyenv install 3.11.9
pyenv install 3.12.3
pyenv install 3.13.5

Exact patch versions are not critical, but should correspond to the py310, py311, py312, and py313 environments defined in tox.ini.

Linux

Installing pyenv

On Linux, pyenv builds Python from source and requires several system dependencies.

Install dependencies (example for Debian/Ubuntu):

sudo apt update
sudo apt install -y \
    build-essential \
    curl \
    git \
    libssl-dev \
    zlib1g-dev \
    libbz2-dev \
    libreadline-dev \
    libsqlite3-dev \
    libncursesw5-dev \
    xz-utils \
    tk-dev \
    libxml2-dev \
    libxmlsec1-dev \
    libffi-dev \
    liblzma-dev

Install pyenv using the official installer:

curl https://pyenv.run | bash

Add the following to your shell configuration file (e.g. ~/.bashrc or ~/.zshrc):

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

Restart your shell and verify the installation:

pyenv --version

Installing Python Versions

Install the required Python versions:

pyenv install 3.10.14
pyenv install 3.11.9
pyenv install 3.12.3
pyenv install 3.13.5

Project Configuration

From the root of the repository, configure the local Python versions:

pyenv local 3.10.14 3.11.9 3.12.3 3.13.5

This creates a .python-version file that ensures tox can locate all required interpreters.

Verify that the interpreters are available:

which python3.10
which python3.11
which python3.12
which python3.13

All paths should resolve to ~/.pyenv/versions/....

Next Steps

Once the required Python versions are installed, tox can be used to run the full test and quality-check matrix.

See Tox-Based Testing for details.