{"record":{"id":"8b61138264c02e7c","repo":"hiyouga/LlamaFactory","slug":"megatron-bridge-is-not-installed-please-install-i-8b6113","errorCode":null,"errorMessage":"megatron-bridge is not installed. Please install it with `pip install --no-build-isolation megatron-bridge`.","messagePattern":"megatron-bridge is not installed\\. Please install it with `pip install --no-build-isolation megatron-bridge`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/train/tuner.py","lineNumber":106,"sourceCode":"        callbacks.append(ModuleProfilerCallback(training_args.profile_modules))\n\n    callbacks.append(ReporterCallback(model_args, data_args, finetuning_args, generating_args))  # add to last\n\n    if finetuning_args.stage in [\"pt\", \"sft\"] and finetuning_args.use_hyper_parallel:\n        if not is_hyper_parallel_available():\n            raise ImportError(\"hyper_parallel is not installed. Please install it with `pip install hyper_parallel`.\")\n        if finetuning_args.stage == \"pt\":\n            from .hyper_parallel import run_pt as run_pt_hp\n\n            run_pt_hp(model_args, data_args, training_args, finetuning_args, callbacks)\n        else:\n            from .hyper_parallel import run_sft as run_sft_hp\n\n            run_sft_hp(model_args, data_args, training_args, finetuning_args, generating_args, callbacks)\n\n    elif finetuning_args.stage in [\"pt\", \"sft\"] and finetuning_args.use_megatron_bridge:\n        if not is_megatron_bridge_available():\n            raise ImportError(\n                \"megatron-bridge is not installed. \"\n                \"Please install it with `pip install --no-build-isolation megatron-bridge`.\"\n            )\n        mb_args = finetuning_args.megatron_bridge_args\n        if mb_args is None:\n            raise ValueError(\"Megatron Bridge arguments are missing. Please set USE_MEGATRON_BRIDGE=1.\")\n        if finetuning_args.stage == \"pt\":\n            from .megatron_bridge import run_pt as run_pt_mb\n\n            run_pt_mb(model_args, data_args, training_args, finetuning_args, mb_args, callbacks)\n        else:\n            from .megatron_bridge import run_sft as run_sft_mb\n\n            run_sft_mb(model_args, data_args, training_args, finetuning_args, mb_args, callbacks)\n\n    elif finetuning_args.stage in [\"pt\", \"sft\", \"dpo\"] and finetuning_args.use_mca:\n        if not is_mcore_adapter_available():\n            raise ImportError(\"mcore_adapter is not installed. Please install it with `pip install mcore-adapter`.\")","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/train/tuner.py#L88-L124","documentation":"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.","triggerScenarios":"Config with `use_megatron_bridge: true` when megatron-bridge is not installed.","commonSituations":"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.","solutions":["Run `pip install --no-build-isolation megatron-bridge` in the training environment (with CUDA/Megatron build prerequisites present).","Verify the import works first: `python -c \"import megatron_bridge\"`.","If you do not intend Megatron training, remove `use_megatron_bridge` from the config."],"exampleFix":"# shell\npip install --no-build-isolation megatron-bridge","handlingStrategy":"validation","validationCode":"from importlib.util import find_spec\ndef megatron_bridge_ready():\n    return find_spec(\"megatron_bridge\") is not None","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Install megatron-bridge with --no-build-isolation in a dedicated env with Megatron build deps.","Verify imports in the env before submitting the training job."],"tags":["megatron","optional-dependency","installation","distributed"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}