mlflow/mlflow · error · ImportError

GEPA >= 0.0.26 is required. Please install it with: `pip ins

Error message

GEPA >= 0.0.26 is required. Please install it with: `pip install 'gepa>=0.0.26'`

What it means

GEPA integration requires gepa >= 0.0.26. MLflow raises a plain ImportError with this message when `import gepa` fails inside GEPAOptimizer.optimize, indicating the package is absent (or an older version installed without the expected API).

Source

Thrown at mlflow/genai/optimize/optimizers/gepa_optimizer.py:143

            target_prompts: The target prompt templates to use. The key is the prompt template
                name and the value is the prompt template.
            enable_tracking: If True (default), automatically log optimization progress.

        Returns:
            The outputs of the prompt optimizer that includes the optimized prompts
            as a dict (prompt template name -> prompt template).
        """
        from mlflow.metrics.genai.model_utils import _parse_model_uri

        if not train_data:
            raise MlflowException.invalid_parameter_value(
                "GEPA optimizer requires `train_data` to be provided."
            )

        try:
            import gepa
        except ImportError as e:
            raise ImportError(
                "GEPA >= 0.0.26 is required. Please install it with: `pip install 'gepa>=0.0.26'`"
            ) from e

        provider, model = _parse_model_uri(self.reflection_model)

        class MlflowGEPAAdapter(gepa.GEPAAdapter):
            """
            MLflow optimization adapter for GEPA optimization

            Args:
                eval_function: Function that evaluates candidate prompts on a dataset.
                prompts_dict: Dictionary mapping prompt names to their templates.
                tracking_enabled: Whether to log traces/metrics/params/artifacts during
                    optimization.
                full_dataset_size: Size of the full training dataset, used to distinguish
                    full validation passes from minibatch evaluations.
            """

View on GitHub (pinned to 6a27f2decc)

Solutions

1. pip install 'gepa>=0.0.26'
2. If gepa is installed but old, upgrade: pip install -U 'gepa>=0.0.26'
3. Check for a local gepa.py or gepa/ directory shadowing the real package
4. Confirm the job/worker environment is the one where gepa was installed

Example fix

// before
ModuleNotFoundError: No module named 'gepa'
// after
$ pip install 'gepa>=0.0.26'

from importlib.metadata import version
try:
    from packaging.version import Version
    assert Version(version("gepa")) >= Version("0.0.26"), "upgrade gepa"
except Exception:
    raise RuntimeError("gepa missing; install: pip install 'gepa>=0.0.26'")

try:
    result = optimize_prompts(..., optimizer_config={"optimizer_type": "gepa"})
except ImportError as e:
    if "GEPA >= 0.0.26" in str(e):
        raise RuntimeError("Install gepa: pip install 'gepa>=0.0.26'") from e
    raise

When it happens

Trigger: Running gepa-based prompt optimization in an environment where the gepa package isn't installed, or where `import gepa` fails for another reason (shadowing module, broken install).

Common situations: Fresh environments without optional deps; pinning an old gepa release; a local file/dir named gepa.py shadowing the package; installing into a different virtualenv than the one running the job.

Related errors

• The 'litellm' package is required for prompt optimization bu
• INVALID_PARAMETER_VALUE
• INVALID_PARAMETER_VALUE
• INVALID_PARAMETER_VALUE
• INVALID_PARAMETER_VALUE

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