{"record":{"id":"72b0c77211f9efac","repo":"hiyouga/LlamaFactory","slug":"hyper-parallel-is-not-installed-please-install-it-72b0c7","errorCode":null,"errorMessage":"hyper_parallel is not installed. Please install it with `pip install hyper_parallel`.","messagePattern":"hyper_parallel is not installed\\. Please install it with `pip install hyper_parallel`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/train/tuner.py","lineNumber":94,"sourceCode":"        callbacks.append(PissaConvertCallback())\n\n    if finetuning_args.use_swanlab:\n        callbacks.append(get_swanlab_callback(finetuning_args))\n\n    if finetuning_args.early_stopping_steps is not None:\n        callbacks.append(EarlyStoppingCallback(early_stopping_patience=finetuning_args.early_stopping_steps))\n\n    if getattr(training_args, \"enable_torch_profiler\", False):\n        callbacks.append(TorchProfilerCallback(training_args))\n\n    if getattr(training_args, \"profile_modules\", None):\n        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.\")","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/train/tuner.py#L76-L112","documentation":"In `_training_function` (src/llamafactory/train/tuner.py:94), enabling `use_hyper_parallel` for pt/sft first checks availability via `is_hyper_parallel_available()`; if the optional `hyper_parallel` package is absent, ImportError with install instructions is raised before any training starts.","triggerScenarios":"Config with `use_hyper_parallel: true` on an environment where `pip install hyper_parallel` was never run (hyper_parallel is an optional extra, not a core dependency).","commonSituations":"Copying a HyperParallel FSDP2 example YAML into a base install; CI images built from the minimal dependency set.","solutions":["Install the package: `pip install hyper_parallel`.","Or install LlamaFactory with the extras that include it, if your fork publishes them.","If FSDP2 HP is not needed, set `use_hyper_parallel: false` and use the standard trainer."],"exampleFix":"# shell\n# before: run fails with ImportError\npip install hyper_parallel  # then rerun training","handlingStrategy":"validation","validationCode":"from importlib.util import find_spec\ndef hyper_parallel_ready():\n    return find_spec(\"hyper_parallel\") is not None","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check optional extras with find_spec before setting their feature flags.","Bake optional dependencies into the Dockerfile used for distributed training."],"tags":["hyper-parallel","fsdp","optional-dependency","installation"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}