{"record":{"id":"ecace669e7c40ec4","repo":"hiyouga/LlamaFactory","slug":"liger-kernel-is-not-installed","errorCode":null,"errorMessage":"Liger kernel is not installed.","messagePattern":"Liger kernel is not installed\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/v1/plugins/model_plugins/kernels/liger_kernel_ops.py","lineNumber":60,"sourceCode":"\n\n@KernelPlugin(\"liger_kernel\").register()\nclass LigerKernel(BaseKernel):\n    \"\"\"Liger Kernel for optimized model training.\"\"\"\n\n    @staticmethod\n    def check_device() -> None:\n        current = get_current_accelerator().type\n        if current not in (DeviceType.CUDA, DeviceType.NPU):\n            raise RuntimeError(f\"LigerKernel requires CUDA or NPU, current accelerator is {current}.\")\n\n    @staticmethod\n    def check_deps() -> None:\n        \"\"\"Checks if the required dependencies for the kernel are available.\"\"\"\n        try:\n            import liger_kernel  # noqa: F401\n        except ImportError:\n            raise RuntimeError(\"Liger kernel is not installed.\") from None\n\n    @staticmethod\n    def _apply(**kwargs) -> \"HFModel\":\n        \"\"\"Applies the Liger kernel to the model.\n\n        Args:\n            **kwargs: Must include ``model``. Optional ``use_kernels`` is a list of Liger op\n                names to enable exclusively, or the string ``\"auto\"`` to use each\n                ``apply_liger_kernel_to_*`` function's signature defaults (same as calling\n                upstream with only ``model``). Optional ``require_logits`` forces non-fused\n                cross entropy when supported.\n\n        Returns:\n            HFModel: The model with Liger kernel applied.\n\n        Raises:\n            ValueError: If the model is not provided.\n            RuntimeError: If dependencies are not met.","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/v1/plugins/model_plugins/kernels/liger_kernel_ops.py#L42-L78","documentation":"LigerKernel.check_deps() probes `import liger_kernel`; if the package is absent it raises RuntimeError ('not installed') with the ImportError chained off. This runs before _apply, so a missing optional dependency fails fast instead of deep inside patching.","triggerScenarios":"Selecting 'liger_kernel' in kernel_config.name without having installed the liger-kernel package (`pip install liger-kernel`).","commonSituations":"Base LlamaFactory install does not pull optional kernel extras; copying a config from a machine that had liger installed; upgrading envs with `--no-deps` dropping optional packages.","solutions":["Install it: `pip install liger-kernel` (or add to the project's kernel extras).","Verify with `python -c \"import liger_kernel; print(liger_kernel.__version__)\"`.","If you did not intend to use it, remove it from kernel_config.name."],"exampleFix":"# before\n# liger-kernel not installed, kernel_config.name: liger_kernel\n\n# after\npip install liger-kernel\npython -c \"import liger_kernel\"  # verify","handlingStrategy":"validation","validationCode":"import importlib.util\nassert importlib.util.find_spec('liger_kernel') is not None, 'pip install liger-kernel'","typeGuard":"def liger_installed() -> bool:\n    \"\"\"True when the liger_kernel package is importable.\"\"\"\n    return importlib.util.find_spec('liger_kernel') is not None","tryCatchPattern":"try:\n    model = KernelPlugin('liger_kernel').apply(model=model)\nexcept RuntimeError as e:\n    if 'not installed' in str(e):\n        raise SystemExit('pip install liger-kernel') from None\n    raise","preventionTips":["Declare kernel extras in the training environment (requirements/uv).","Verify optional imports in a preflight check step.","Keep per-kernel dependency lists documented next to configs."],"tags":["kernels","liger","dependencies","install"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}