mlflow/mlflow · error · MlflowException

An error occurred while downloading the dependency wheels: {

Error message

An error occurred while downloading the dependency wheels: {e.stdout}

What it means

MLflow runs `pip wheel` as a subprocess to download dependency wheels for a WheeledModel. If the subprocess exits non-zero (network failure, unresolvable dependencies, bad index), the CalledProcessError is re-raised as an MlflowException containing pip's combined stdout output.

Source

Thrown at mlflow/models/wheeled_model.py:279

                    sys.executable,
                    "-m",
                    "pip",
                    "wheel",
                    pip_wheel_options,
                    "--wheel-dir",
                    dst_path,
                    "-r",
                    pip_requirements_path,
                    "--no-cache-dir",
                    "--progress-bar=off",
                ],
                check=True,
                stdout=subprocess.PIPE,
                stderr=subprocess.STDOUT,
                env=env,
            )
        except subprocess.CalledProcessError as e:
            raise MlflowException(
                f"An error occurred while downloading the dependency wheels: {e.stdout}"
            )

    def _overwrite_pip_requirements_with_wheels(self, pip_requirements_path, wheels_dir):
        """
        Overwrites the requirements.txt with the wheels of the required dependencies.

        Args:
            pip_requirements_path: Path to requirements.txt in the model directory.
            wheels_dir: Path to directory where wheels are stored.
        """
        wheels = []
        with open(pip_requirements_path, "w") as wheels_requirements:
            for wheel_file in os.listdir(wheels_dir):
                if wheel_file.endswith(".whl"):
                    complete_wheel_file = os.path.join(_WHEELS_FOLDER_NAME, wheel_file)
                    wheels.append(complete_wheel_file)
                    wheels_requirements.write(complete_wheel_file + "\n")

View on GitHub (pinned to 6a27f2decc)

Solutions

1. Read e.stdout in the message to see pip's actual failure and fix the underlying pip error
2. Verify network/index access (PIP_INDEX_URL, proxy settings, credentials) in the environment
3. Resolve version conflicts in the model's requirements.txt or conda env
4. Ensure wheels exist for your platform/Python version or add --pre / alternative sources appropriately
5. Re-run after fixing; the error is a wrapper, not the root cause

Example fix

// before
export PIP_INDEX_URL=https://internal.example.com/simple  # 401 without creds
WheeledModel(model_uri=uri).add_libraries()

// after
export PIP_INDEX_URL=https://user:token@internal.example.com/simple
WheeledModel(model_uri=uri).add_libraries()

import subprocess
# Pre-check index reachability before wheel download
subprocess.run(["pip", "index", "versions", "numpy"], check=True, capture_output=True)

from mlflow.exceptions import MlflowException
import time
for attempt in range(3):
    try:
        wheeled.add_libraries()
        break
    except MlflowException as e:
        if "downloading the dependency wheels" in str(e) and attempt < 2:
            time.sleep(2 ** attempt)  # transient network failures
        else:
            print(e)  # shows pip stdout for root cause
            raise

When it happens

Trigger: pip wheel failing during WheeledModel.add_libraries()/save_model/log due to unreachable package index, authentication failures on a private index, dependency resolution conflicts, no matching wheel for the platform/Python version, or disk/permission problems.

Common situations: Corporate proxy blocking PyPI; private index requiring credentials not configured; packages without wheels for the current Python version; conflicting pinned versions in requirements.txt; offline CI runners.

Related errors

• INVALID_PARAMETER_VALUE
• Authentication check timed out
• Connection check timed out
• Failed to load base model '{base_model}'. If the model has m
• Sanitization request failed: {e.detail}

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