hiyouga/LlamaFactory · error · ImportError

megatron-bridge is not installed. Please install it with `pi

Error message

megatron-bridge is not installed. Please install it with `pip install --no-build-isolation megatron-bridge`.

What it means

In the Megatron-Bridge branch (src/llamafactory/train/tuner.py:106), `use_megatron_bridge: true` for pt/sft requires the optional `megatron-bridge` package. Its absence raises ImportError; note the required install uses `--no-build-isolation` because Megatron components need the ambient build environment.

Source

Thrown at src/llamafactory/train/tuner.py:106

        callbacks.append(ModuleProfilerCallback(training_args.profile_modules))

    callbacks.append(ReporterCallback(model_args, data_args, finetuning_args, generating_args))  # add to last

    if finetuning_args.stage in ["pt", "sft"] and finetuning_args.use_hyper_parallel:
        if not is_hyper_parallel_available():
            raise ImportError("hyper_parallel is not installed. Please install it with `pip install hyper_parallel`.")
        if finetuning_args.stage == "pt":
            from .hyper_parallel import run_pt as run_pt_hp

            run_pt_hp(model_args, data_args, training_args, finetuning_args, callbacks)
        else:
            from .hyper_parallel import run_sft as run_sft_hp

            run_sft_hp(model_args, data_args, training_args, finetuning_args, generating_args, callbacks)

    elif finetuning_args.stage in ["pt", "sft"] and finetuning_args.use_megatron_bridge:
        if not is_megatron_bridge_available():
            raise ImportError(
                "megatron-bridge is not installed. "
                "Please install it with `pip install --no-build-isolation megatron-bridge`."
            )
        mb_args = finetuning_args.megatron_bridge_args
        if mb_args is None:
            raise ValueError("Megatron Bridge arguments are missing. Please set USE_MEGATRON_BRIDGE=1.")
        if finetuning_args.stage == "pt":
            from .megatron_bridge import run_pt as run_pt_mb

            run_pt_mb(model_args, data_args, training_args, finetuning_args, mb_args, callbacks)
        else:
            from .megatron_bridge import run_sft as run_sft_mb

            run_sft_mb(model_args, data_args, training_args, finetuning_args, mb_args, callbacks)

    elif finetuning_args.stage in ["pt", "sft", "dpo"] and finetuning_args.use_mca:
        if not is_mcore_adapter_available():
            raise ImportError("mcore_adapter is not installed. Please install it with `pip install mcore-adapter`.")

View on GitHub (pinned to f28afaf635)

Solutions

1. Run `pip install --no-build-isolation megatron-bridge` in the training environment (with CUDA/Megatron build prerequisites present).
2. Verify the import works first: `python -c "import megatron_bridge"`.
3. If you do not intend Megatron training, remove `use_megatron_bridge` from the config.

Example fix

# shell
pip install --no-build-isolation megatron-bridge

from importlib.util import find_spec
def megatron_bridge_ready():
    return find_spec("megatron_bridge") is not None

When it happens

Trigger: Config with `use_megatron_bridge: true` when megatron-bridge is not installed.

Common situations: Large-scale pretraining setups copied onto machines without the Megatron toolchain; forgetting that `--no-build-isolation` is required so a naive `pip install megatron-bridge` may also fail to build.

Related errors

• Pipeline parallel size should be smaller than the number of
• `tensor_model_parallel_size` must be >= 1.
• `pipeline_model_parallel_size` must be >= 1.
• Total Megatron Bridge parallel size ({parallel_size}) exceed
• Total Megatron Bridge parallel size ({parallel_size}) must d

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