hiyouga/LlamaFactory · error · RuntimeError

Liger kernel is not installed.

Error message

Liger kernel is not installed.

What it means

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.

Source

Thrown at src/llamafactory/v1/plugins/model_plugins/kernels/liger_kernel_ops.py:60

@KernelPlugin("liger_kernel").register()
class LigerKernel(BaseKernel):
    """Liger Kernel for optimized model training."""

    @staticmethod
    def check_device() -> None:
        current = get_current_accelerator().type
        if current not in (DeviceType.CUDA, DeviceType.NPU):
            raise RuntimeError(f"LigerKernel requires CUDA or NPU, current accelerator is {current}.")

    @staticmethod
    def check_deps() -> None:
        """Checks if the required dependencies for the kernel are available."""
        try:
            import liger_kernel  # noqa: F401
        except ImportError:
            raise RuntimeError("Liger kernel is not installed.") from None

    @staticmethod
    def _apply(**kwargs) -> "HFModel":
        """Applies the Liger kernel to the model.

        Args:
            **kwargs: Must include ``model``. Optional ``use_kernels`` is a list of Liger op
                names to enable exclusively, or the string ``"auto"`` to use each
                ``apply_liger_kernel_to_*`` function's signature defaults (same as calling
                upstream with only ``model``). Optional ``require_logits`` forces non-fused
                cross entropy when supported.

        Returns:
            HFModel: The model with Liger kernel applied.

        Raises:
            ValueError: If the model is not provided.
            RuntimeError: If dependencies are not met.

View on GitHub (pinned to f28afaf635)

Solutions

1. Install it: `pip install liger-kernel` (or add to the project's kernel extras).
2. Verify with `python -c "import liger_kernel; print(liger_kernel.__version__)"`.
3. If you did not intend to use it, remove it from kernel_config.name.

Example fix

# before
# liger-kernel not installed, kernel_config.name: liger_kernel

# after
pip install liger-kernel
python -c "import liger_kernel"  # verify

import importlib.util
assert importlib.util.find_spec('liger_kernel') is not None, 'pip install liger-kernel'

def liger_installed() -> bool:
    """True when the liger_kernel package is importable."""
    return importlib.util.find_spec('liger_kernel') is not None

try:
    model = KernelPlugin('liger_kernel').apply(model=model)
except RuntimeError as e:
    if 'not installed' in str(e):
        raise SystemExit('pip install liger-kernel') from None
    raise

When it happens

Trigger: Selecting 'liger_kernel' in kernel_config.name without having installed the liger-kernel package (`pip install liger-kernel`).

Common situations: 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.

Related errors

• Flash Linear Attention and FSDPTurbo are required for this k
• LigerKernel requires CUDA or NPU, current accelerator is {cu
• Unknown Liger op(s) {sorted(ops)} for model_type={model_type
• cross_entropy and fused_linear_cross_entropy cannot both be
• The installed Transformers-KT does not provide `TrainingArgu

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