mlflow/mlflow · error · MlflowException

Could not find python version that matches {version_prefix}

Error message

Could not find python version that matches {version_prefix}

What it means

MLflow uses pyenv to resolve the newest installed pyenv Python matching the model's requested version prefix (e.g. '3.10'); this error is raised when no pyenv-managed Python version matches the prefix. It means pyenv is available but no compatible version is installed (or listed).

Source

Thrown at mlflow/utils/virtualenv.py:91

        return _DATABRICKS_PYENV_BIN_PATH
    return shutil.which("pyenv")


def _find_latest_installable_python_version(version_prefix):
    """
    Find the latest installable python version that matches the given version prefix
    from the output of `pyenv install --list`. For example, `version_prefix("3.8")` returns '3.8.x'
    where 'x' represents the latest micro version in 3.8.
    """
    lines = _exec_cmd(
        [_get_pyenv_bin_path(), "install", "--list"],
        capture_output=True,
        shell=is_windows(),
    ).stdout.splitlines()
    semantic_versions = filter(_SEMANTIC_VERSION_REGEX.match, map(str.strip, lines))
    matched = [v for v in semantic_versions if v.startswith(version_prefix)]
    if not matched:
        raise MlflowException(f"Could not find python version that matches {version_prefix}")
    return max(matched, key=Version)


def _install_python(version, pyenv_root=None, capture_output=False):
    """Installs a specified version of python with pyenv and returns a path to the installed python
    binary.

    Args:
        version: Python version to install.
        pyenv_root: The value of the "PYENV_ROOT" environment variable used when running
            `pyenv install` which installs python in `{PYENV_ROOT}/versions/{version}`.
        capture_output: Set the `capture_output` argument when calling `_exec_cmd`.

    Returns:
        Path to the installed python binary.
    """
    version = (
        version

View on GitHub (pinned to 6a27f2decc)

Solutions

1. Run `pyenv install --list | grep '^ 3\.'` to see available versions, then install the matching one: `pyenv install 3.10.14` (use the exact minor the model requests).
2. If the requested version is no longer listed by pyenv, update pyenv (`pyenv update` or reinstall) so its version list is current.
3. Resave/re-log the model with a python_version that pyenv can satisfy, or omit python_version to use the current environment.
4. Verify `pyenv versions` output and that MLflow's `pyenv install --list` subprocess actually succeeds (PATH/permissions).

Example fix

# before
# MLmodel: python_version: 3.11 (only 3.10.x installed in pyenv)
MlflowException: Could not find python version that matches 3.11

# after
$ pyenv install 3.11.9
$ mlflow models serve -m model_dir --env-manager virtualenv  # resolves 3.11.9

import subprocess
prefix = "3.10"  # the model's python_version
out = subprocess.run(["pyenv", "install", "--list"], capture_output=True, text=True).stdout
import re
versions = [v for v in map(str.strip, out.splitlines()) if re.match(r"^\d+\.\d+\.\d+$", v)]
assert any(v.startswith(prefix) for v in versions), f"pyenv has no {prefix}.x version installed/listed; run: pyenv install $(pyenv install --list | grep -F '{prefix}.' | tail -1)"

from mlflow.exceptions import MlflowException
try:
    mlflow.models.serve(model_uri, env_manager="virtualenv")
except MlflowException as e:
    if "Could not find python version" in str(e):
        # install the missing pyenv python or re-log the model with an available version
        ...

When it happens

Trigger: A model's MLmodel pyfunc.python_version (e.g. 3.11) has no corresponding pyenv-installed version: _install_python -> _find_latest_installable_python_version runs `pyenv install --list`, filters by _SEMANTIC_VERSION_REGEX and the prefix, and the matched list is empty.

Common situations: Only a few Python versions installed via pyenv while the model was logged with a different one; pyenv lists non-semantic versions (e.g. 3.10-dev, rc builds) that are filtered out; `pyenv install --list` output empty or truncated due to a stale pyenv; typo in python_version when logging the model.

Related errors

• Could not find the pyenv binary. See {url} for installation
• Failed to exec '%s -m %s', needed to access artifacts within
• Invalid value for `env_manager`: {env_manager}. Must be one
• Failed to restore model environment using uv sync. Ensure th
• Use of conda is discouraged. If you use it, please ensure th

AI-assisted analysis of mlflow/mlflow@6a27f2decc (2026-08-29). Data as JSON: /api/errors/873d93a18c4414d2. Report an issue: GitHub.