{"record":{"id":"fee9ea43851a4f90","repo":"mlflow/mlflow","slug":"gepa-0-0-26-is-required-please-install-it-with","errorCode":null,"errorMessage":"GEPA >= 0.0.26 is required. Please install it with: `pip install 'gepa>=0.0.26'`","messagePattern":"GEPA >= 0\\.0\\.26 is required\\. Please install it with: `pip install 'gepa>=0\\.0\\.26'`","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"mlflow/genai/optimize/optimizers/gepa_optimizer.py","lineNumber":143,"sourceCode":"            target_prompts: The target prompt templates to use. The key is the prompt template\n                name and the value is the prompt template.\n            enable_tracking: If True (default), automatically log optimization progress.\n\n        Returns:\n            The outputs of the prompt optimizer that includes the optimized prompts\n            as a dict (prompt template name -> prompt template).\n        \"\"\"\n        from mlflow.metrics.genai.model_utils import _parse_model_uri\n\n        if not train_data:\n            raise MlflowException.invalid_parameter_value(\n                \"GEPA optimizer requires `train_data` to be provided.\"\n            )\n\n        try:\n            import gepa\n        except ImportError as e:\n            raise ImportError(\n                \"GEPA >= 0.0.26 is required. Please install it with: `pip install 'gepa>=0.0.26'`\"\n            ) from e\n\n        provider, model = _parse_model_uri(self.reflection_model)\n\n        class MlflowGEPAAdapter(gepa.GEPAAdapter):\n            \"\"\"\n            MLflow optimization adapter for GEPA optimization\n\n            Args:\n                eval_function: Function that evaluates candidate prompts on a dataset.\n                prompts_dict: Dictionary mapping prompt names to their templates.\n                tracking_enabled: Whether to log traces/metrics/params/artifacts during\n                    optimization.\n                full_dataset_size: Size of the full training dataset, used to distinguish\n                    full validation passes from minibatch evaluations.\n            \"\"\"\n","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/mlflow/mlflow/blob/6a27f2decc0b76eb1b54af31849784addb357dbc/mlflow/genai/optimize/optimizers/gepa_optimizer.py#L125-L161","documentation":"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).","triggerScenarios":"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).","commonSituations":"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.","solutions":["pip install 'gepa>=0.0.26'","If gepa is installed but old, upgrade: pip install -U 'gepa>=0.0.26'","Check for a local gepa.py or gepa/ directory shadowing the real package","Confirm the job/worker environment is the one where gepa was installed"],"exampleFix":"// before\nModuleNotFoundError: No module named 'gepa'\n// after\n$ pip install 'gepa>=0.0.26'","handlingStrategy":"validation","validationCode":"from importlib.metadata import version\ntry:\n    from packaging.version import Version\n    assert Version(version(\"gepa\")) >= Version(\"0.0.26\"), \"upgrade gepa\"\nexcept Exception:\n    raise RuntimeError(\"gepa missing; install: pip install 'gepa>=0.0.26'\")","typeGuard":null,"tryCatchPattern":"try:\n    result = optimize_prompts(..., optimizer_config={\"optimizer_type\": \"gepa\"})\nexcept ImportError as e:\n    if \"GEPA >= 0.0.26\" in str(e):\n        raise RuntimeError(\"Install gepa: pip install 'gepa>=0.0.26'\") from e\n    raise","preventionTips":["Pin gepa>=0.0.26 in requirements for optimization environments","Ensure no local gepa.py/gepa/ directory shadows the installed package","Install deps into the same venv/container that runs the optimization job"],"tags":["mlflow","genai","gepa","dependency","version"],"backgroundTag":"missing-dependency","analyzedSha":"6a27f2decc0b76eb1b54af31849784addb357dbc","analyzedAt":"2026-08-29T20:54:51.419Z","schemaVersion":2},"datasetVersion":"2026-08-29T22:17:34.462Z"}