Lightning-AI/pytorch-lightning · error · ModuleNotFoundError

`synchronous` requires mlflow>=2.8.0

Error message

`synchronous` requires mlflow>=2.8.0

What it means

ModuleNotFoundError raised in MLFlowLogger.__init__ when the synchronous argument is used but the installed mlflow version predates the synchronous logging API (added in mlflow 2.8.0). Lightning gates the kwarg on the _MLFLOW_SYNCHRONOUS_AVAILABLE version check.

Source

Thrown at src/lightning/pytorch/loggers/mlflow.py:132

    LOGGER_JOIN_CHAR = "-"

    def __init__(
        self,
        experiment_name: str = "lightning_logs",
        run_name: Optional[str] = None,
        tracking_uri: Optional[str] = os.getenv("MLFLOW_TRACKING_URI"),
        tags: Optional[dict[str, Any]] = None,
        save_dir: Optional[str] = "./mlruns",
        log_model: Literal[True, False, "all"] = False,
        prefix: str = "",
        artifact_location: Optional[str] = None,
        run_id: Optional[str] = None,
        synchronous: Optional[bool] = None,
    ):
        if not _MLFLOW_AVAILABLE:
            raise ModuleNotFoundError(str(_MLFLOW_AVAILABLE))
        if synchronous is not None and not _MLFLOW_SYNCHRONOUS_AVAILABLE:
            raise ModuleNotFoundError("`synchronous` requires mlflow>=2.8.0")
        super().__init__()
        if not tracking_uri:
            tracking_uri = f"{LOCAL_FILE_URI_PREFIX}{save_dir}"

        self._experiment_name = experiment_name
        self._experiment_id: Optional[str] = None
        self._tracking_uri = tracking_uri
        self._run_name = run_name
        self._run_id = run_id
        self.tags = tags
        self._log_model = log_model
        self._logged_model_time: dict[str, float] = {}
        self._checkpoint_callback: Optional[ModelCheckpoint] = None
        self._prefix = prefix
        self._artifact_location = artifact_location
        self._log_batch_kwargs = {} if synchronous is None else {"synchronous": synchronous}
        self._initialized = False

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. pip install -U 'mlflow>=2.8.0'
2. Or drop the synchronous kwarg if async behavior is acceptable
3. Pin mlflow>=2.8.0 in your requirements to prevent downgrade

Example fix

# before: mlflow 2.5 installed
logger = MLFlowLogger(experiment_name='e', synchronous=True)
# after
pip install 'mlflow>=2.8.0'
logger = MLFlowLogger(experiment_name='e', synchronous=True)

import mlflow
from packaging.version import Version
use_sync = Version(mlflow.__version__) >= Version("2.8.0")
logger = MLFlowLogger(..., synchronous=True if use_sync else None)

When it happens

Trigger: Instantiating MLFlowLogger(..., synchronous=True/False) with mlflow<2.8.0 installed (also raises plain ModuleNotFoundError(str(_MLFLOW_AVAILABLE)) if mlflow is missing entirely — this specific message requires mlflow present but old).

Common situations: Pinned old mlflow in requirements, or an environment resolver downgraded mlflow; user copies example code that uses synchronous logging.

Related errors

• SpikeDetection requires `torchmetrics>=1.0.0` Please upgrade
• Experiment is not initialized
• NeptuneLogger is no longer supported. Neptune has been sunse
• Providing log_model={log_model} and offline={offline} is an
• LitLogger does not support `log_graph`

AI-assisted analysis of Lightning-AI/pytorch-lightning@9fed5c27d2 (2026-08-28). Data as JSON: /api/errors/23e10d7f5c318778. Report an issue: GitHub.