hiyouga/LlamaFactory · error · ImportError

megatron-bridge is required when USE_MEGATRON_BRIDGE=1. Plea

Error message

megatron-bridge is required when USE_MEGATRON_BRIDGE=1. Please install `megatron-bridge` and its dependencies.

What it means

This ImportError is raised in get_train_args when the environment variable USE_MEGATRON_BRIDGE=1 is set but the optional megatron-bridge package is not importable (is_megatron_bridge_available() returns False). Megatron Bridge is an optional backend, so the dependency check runs before _parse_train_mbridge_args parses its arguments.

Source

Thrown at src/llamafactory/hparams/parser.py:401

        parser, args, allow_extra_keys=allow_extra_keys
    )
    model_args._kt_inference_config = kt_args.kt_config
    return model_args, data_args, eval_args, finetuning_args


def get_ray_args(args: dict[str, Any] | list[str] | None = None) -> RayArguments:
    parser = HfArgumentParser(RayArguments)
    (ray_args,) = _parse_args(parser, args, allow_extra_keys=True)
    return ray_args


def get_train_args(args: dict[str, Any] | list[str] | None = None) -> _TRAIN_CLS:
    mb_args = None
    if is_env_enabled("USE_MCA"):
        model_args, data_args, training_args, finetuning_args, generating_args = _parse_train_mca_args(args)
    elif is_env_enabled("USE_MEGATRON_BRIDGE"):
        if not is_megatron_bridge_available():
            raise ImportError(
                "megatron-bridge is required when USE_MEGATRON_BRIDGE=1. "
                "Please install `megatron-bridge` and its dependencies."
            )
        model_args, data_args, training_args, finetuning_args, mb_args, generating_args = _parse_train_mbridge_args(
            args
        )
    else:
        model_args, data_args, training_args, finetuning_args, generating_args = _parse_train_args(args)
        finetuning_args.use_mca = False
        finetuning_args.use_megatron_bridge = False

    # Setup logging
    if training_args.should_log:
        _set_transformers_logging()

    # Check arguments
    if finetuning_args.stage != "sft":
        if training_args.predict_with_generate:

View on GitHub (pinned to f28afaf635)

Solutions

1. Install the backend: pip install megatron-bridge (or the documented extras, e.g. pip install llamafactory[megatron] / requirements listed in the Megatron Bridge docs).
2. If you did not intend Megatron Bridge, unset the variable: unset USE_MEGATRON_BRIDGE (or remove it from .env / CI env) and re-run.
3. Verify with python -c "from llamafactory.extras import is_megatron_bridge_available" or simply retry the command after install.

Example fix

# before
USE_MEGATRON_BRIDGE=1 llamafactory-cli train cfg.yaml  # ImportError

# after
pip install megatron-bridge
USE_MEGATRON_BRIDGE=1 llamafactory-cli train cfg.yaml

import importlib.util, os

if os.environ.get("USE_MEGATRON_BRIDGE") == "1":
    if importlib.util.find_spec("megatron_bridge") is None:
        raise SystemExit("USE_MEGATRON_BRIDGE=1 requires megatron-bridge; pip install megatron-bridge")

When it happens

Trigger: Running any train command with USE_MEGATRON_BRIDGE=1 in an environment where megatron-bridge (and its Megatron dependencies) is not installed — e.g. a fresh venv, a container built from the base LlamaFactory image, or after downgrading/uninstalling extras.

Common situations: CI jobs or Docker images that set USE_MEGATRON_BRIDGE=1 globally while the image only includes the base requirements; following Megatron Bridge docs on a machine where only pip install llamafactory was run; stale shell profile exporting the variable from earlier experiments.

Related errors

• mcore_adapter is required when USE_MCA=1. Please install `mc
• Pipeline parallel size should be smaller than the number of
• Megatron Bridge arguments are missing. Please set USE_MEGATR
• The installed kt-kernel does not provide the activation chec
• Qwen2VL requires 3D position ids for mrope.

AI-assisted analysis of hiyouga/LlamaFactory@f28afaf635 (2026-08-14). Data as JSON: /api/errors/aba9cadeb8e6ecbf. Report an issue: GitHub.