lima-vm/lima · error

krunkit CLI not found in PATH. Install it via: brew tap slp/

Error message

krunkit CLI not found in PATH. Install it via:
brew tap slp/krun
brew install krunkit

What it means

The krunkit driver requires the `krunkit` CLI binary to launch libkrun VMs on macOS. During config validation (validateConfig, invoked by Validate and fillConfig), Lima runs exec.LookPath(vmType) to confirm the binary is on PATH; if it is missing, validation aborts with install instructions because no VM can be started without it.

Source

Thrown at pkg/driver/krunkit/krunkit_driver_darwin_arm64.go:227

	return nil
}

func validateConfig(cfg *limatype.LimaYAML) error {
	if cfg == nil {
		return errors.New("configuration is nil")
	}
	macOSProductVersion, err := osutil.ProductVersion()
	if err != nil {
		return err
	}
	if macOSProductVersion.LessThan(*semver.New("13.0.0")) {
		return errors.New("krunkit driver requires macOS 13 or higher to run")
	}
	if cfg.Arch != nil && !limatype.IsNativeArch(*cfg.Arch) {
		return fmt.Errorf("unsupported arch: %#q (krunkit requires native arch)", *cfg.Arch)
	}
	if _, err := exec.LookPath(vmType); err != nil {
		return errors.New("krunkit CLI not found in PATH. Install it via:\nbrew tap slp/krun\nbrew install krunkit")
	}
	// Also check if krunkit version >= 1.2.1 because of the vsock forwarder feature
	if err := checkKrunkitVersion(); err != nil {
		return err
	}

	if cfg.MountType != nil && (*cfg.MountType != limatype.VIRTIOFS && *cfg.MountType != limatype.REVSSHFS) {
		return fmt.Errorf("field `mountType` must be %#q or %#q for krunkit driver, got %#q", limatype.VIRTIOFS, limatype.REVSSHFS, *cfg.MountType)
	}

	if cfg.TPM != nil && *cfg.TPM {
		return errors.New("field `tpm` is not supported in krunkit driver")
	}

	if cfg.NestedVirtualization != nil && *cfg.NestedVirtualization {
		if macOSProductVersion.LessThan(*semver.New("15.0.0")) {
			return errors.New("nested virtualization requires macOS 15 or newer")
		}

View on GitHub (pinned to dd909d0973)

Solutions

1. Install krunkit: `brew tap slp/krun && brew install krunkit`
2. Verify it is resolvable: `which krunkit`; if installed elsewhere, add its directory to PATH
3. If krunkit is not needed, switch the instance config to vmType qemu or vz

Example fix

// before (lima.yaml)
vmType: krunkit
// after (if krunkit is intentionally not installed)
vmType: qemu

if _, err := exec.LookPath("krunkit"); err != nil {
    return fmt.Errorf("krunkit not installed; run: brew tap slp/krun && brew install krunkit")
}

When it happens

Trigger: Calling limactl validate or limactl start on a config whose vmType is krunkit on macOS while `krunkit` is not installed or not in any PATH directory.

Common situations: Fresh macOS machines where krunkit was never installed; Homebrew-installed binary not linked into PATH; using a Lima config copied from another machine; PATH stripped in non-interactive shells/CI.

Related errors

• unimplemented by the krunkit driver
• failed to load disk %#q: %w
• failed to run attach disk %#q, in use by instance %#q
• failed to lock disk %#q: %w
• failed to convert extra disk %#q to raw: %w

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/622935c95ab8d7fc. Report an issue: GitHub.