Python version mismatch (.python-version vs CI) in CI

Your project declares a Python version (in .python-version, pyproject.toml, or tox.ini) but CI provisioned a different one. The mismatch surfaces as syntax, dependency, or behavior differences.

What this error means

CI runs on, say, 3.10 while your code targets 3.12 - producing SyntaxErrors, missing-feature errors, or dependencies that resolve differently than locally.

$ python --version
Python 3.10.14        # CI runner
# .python-version says 3.12

Common causes

setup-python not set to the declared version

The workflow hardcodes a version that does not match what your project files declare.

A default image interpreter overriding the pin

Without setup-python honoring .python-version, the job uses the image default instead of your pin.

How to fix it

Drive setup-python from the project file

Use the python-version-file input so CI matches your declared version exactly.

- uses: actions/setup-python@v5
  with:
    python-version-file: '.python-version'

Test the full declared matrix

Run every version in requires-python so the mismatch cannot hide.

strategy:
  matrix:
    python-version: ['3.10', '3.11', '3.12']

How to prevent it

• Source the CI version from .python-version or pyproject.toml.
• Keep requires-python and the CI matrix in agreement.
• Pin the interpreter explicitly; never rely on the image default.

Related guides