hiyouga/LlamaFactory · error · ImportError

mcore_adapter is not installed. Please install it with `pip

Error message

mcore_adapter is not installed. Please install it with `pip install mcore-adapter`.

What it means

The MCA (Megatron-core adapter) branch (src/llamafactory/train/tuner.py:124) supports pt/sft/dpo when `use_mca: true`; it first checks `is_mcore_adapter_available()` and raises ImportError if the optional `mcore-adapter` package is missing.

Source

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

            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`.")
        if finetuning_args.stage == "pt":
            from .mca import run_pt as run_pt_mca

            run_pt_mca(model_args, data_args, training_args, finetuning_args, callbacks)
        elif finetuning_args.stage == "sft":
            from .mca import run_sft as run_sft_mca

            run_sft_mca(model_args, data_args, training_args, finetuning_args, callbacks)
        elif finetuning_args.stage == "dpo":
            from .mca import run_dpo as run_dpo_mca

            run_dpo_mca(model_args, data_args, training_args, finetuning_args, callbacks)

    elif finetuning_args.stage == "pt":
        run_pt(model_args, data_args, training_args, finetuning_args, callbacks)
    elif finetuning_args.stage == "sft":
        run_sft(model_args, data_args, training_args, finetuning_args, generating_args, callbacks)
    elif finetuning_args.stage == "rm":

View on GitHub (pinned to f28afaf635)

Solutions

Install the adapter: `pip install mcore-adapter`.
Verify with `python -c "import mcore_adapter"` and rerun.
If Megatron-core is not required, set `use_mca: false`.

Example fix

# shell
pip install mcore-adapter

Defensive patterns

Strategy: validation

Validate before calling

from importlib.util import find_spec
def mca_ready():
    return find_spec("mcore_adapter") is not None

Prevention

Probe find_spec('mcore_adapter') before enabling use_mca.
Keep a requirements-extra file per distributed backend for reproducible envs.

When it happens

Trigger: Config with `use_mca: true` on an environment without `pip install mcore-adapter`.

Common situations: Adopting Megatron-core training for DPO/SFT on a fresh machine or container built from base requirements.

Related errors

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