could not find whkd, please make sure it is installed before

Error message

could not find whkd, please make sure it is installed before using the --whkd flag

What it means

komorebic (komorebi's CLI companion) checks that the external hotkey daemon whkd is on PATH when the --whkd flag is passed, using the `which` crate. If whkd cannot be found, it bails with a message telling the user to install whkd first. This is a startup-time dependency check, not a runtime failure.

Source

Thrown at komorebic/src/main.rs:2374

            ))?;
        }
        SubCommand::Start(args) => {
            if args.ahk {
                println!(
                    "EOL: The --ahk flag is now end-of-life and will not receive any further updates or bug fixes"
                );
            }

            let mut ahk: String = String::from("autohotkey.exe");

            if let Ok(komorebi_ahk_exe) = std::env::var("KOMOREBI_AHK_EXE")
                && which(&komorebi_ahk_exe).is_ok()
            {
                ahk = komorebi_ahk_exe;
            }

            if args.whkd && which("whkd").is_err() {
                bail!(
                    "could not find whkd, please make sure it is installed before using the --whkd flag"
                );
            }

            if args.masir && which("masir").is_err() {
                bail!(
                    "could not find masir, please make sure it is installed before using the --masir flag"
                );
            }

            if args.ahk && which(&ahk).is_err() {
                bail!(
                    "could not find autohotkey, please make sure it is installed before using the --ahk flag"
                );
            }

            let mut buf: PathBuf;

View on GitHub (pinned to e0709f02bf)

Solutions

Install whkd (e.g. `scoop install whkd` or `cargo install whkd`)
Verify with `which whkd` / `whkd --version` that it resolves on PATH
Add whkd's install directory to your PATH environment variable, then restart the shell
Drop the --whkd flag if you manage hotkeys with AutoHotkey or another daemon instead

Example fix

# before
komorebic start --whkd
# error: could not find whkd
# after
scoop install whkd
komorebic start --whkd

Defensive patterns

Strategy: validation

Validate before calling

# shell pre-flight
command -v whkd >/dev/null 2>&1 || { echo "install whkd first"; exit 1; }
komorebic start --whkd

Prevention

Install whkd as part of your komorebi setup script before running komorebic start --whkd
Verify PATH contains whkd's install location (scoop shims, cargo bin)
Run `which whkd` in the same shell/profile that launches komorebic
Use --whkd only when you actually rely on whkd for hotkeys; omit it otherwise

When it happens

Trigger: Running komorebic start --whkd when whkd is not installed or not on the PATH environment variable; misspelled or incomplete installation of whkd.

Common situations: Fresh komorebi installs where whkd (a separate project) was never installed; whkd installed via scoop/cargo into a directory not on PATH; running komorebic from an environment with a different PATH (e.g. service or IDE terminal).

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

AI-assisted analysis of LGUG2Z/komorebi@e0709f02bf (2026-09-06). Data as JSON: /api/errors/aaface9d9ec6fb22. Report an issue: GitHub.