Installation

Packages are available install via Scoop and WinGet on Windows, and Homebrew and Nix on macOS.

You may also build from source on both platforms.

komorebi for Mac availability

komorebi for Mac is currently only available in early access to GitHub Sponsors on the $10/month tier.

Suggested system settings

Windows

It is highly recommended that you enable support for long paths in Windows by running the following command in an Administrator Terminal before installing komorebi.

Set-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1

It is also highly recommended that you enable the “Turn off all unnecessary animations (when possible)” option in “Control Panel > Ease of Access > Ease of Access Centre / Make the computer easier to see” for the best performance with komorebi.

macOS

Go to System Settings -> Desktop & Dock -> Mission Control -> Displays have separate Spaces and disable this option if you are using more than one monitor.

komorebi is scoped to a single macOS space (the one that is active when the process is started), which means that you can still use other Spaces as if komorebi were not running at all. If you are using monitors with the above option enabled, komorebi will only be listening to events from the Space on the monitor which it was launched on.

Go to System Settings -> Desktop & Dock -> Mission Control -> Group windows by application and disable this option if you like to use mission control.

Installation via Package Managers

Windows $Env:PATH Issues

Issues with komorebi and related commands not being recognized in the terminal ultimately come down to the $Env:PATH environment variable not being correctly configured by your package manager and should not be raised as bugs or issues either on the GitHub repository or Discord server.

Scoop

Add the extras bucket

scoop bucket add extras

Install komorebi and whkd

scoop install komorebi whkd

WinGet

Install komorebi and whkd

winget install LGUG2Z.komorebi
winget install LGUG2Z.whkd

Note

You must restart your terminal after installing with WinGet.

Homebrew

Add lgug2z/tap

brew tap lgug2z/tap

Install komorebi and skhd

brew install lgug2z/tap/komorebi-for-mac-nightly
brew install skhd

Nix

Ensure that your system Flake is configured to use your GitHub token so that you can add a private repository as an input.

flake.nix

{
  nix = {
    settings = {
      access-tokens = [
        "github.com=YOUR ACCESS TOKEN"
      ];
    };
  };
}

Add the repository as an input:

flake.nix

{
  inputs.komorebi-for-mac.url = "github:KomoCorp/komorebi-for-mac";
}

Add the overlay to your system’s nixpkgs configuration:

flake.nix

{
  pkgs = import nixpkgs {
    inherit system;
    overlays = [ komorebi-for-mac.overlays.default ];
    # the rest of your pkgs configuration
  };
}

Add pkgs.komorebi-full to environment.systemPackages (you may also add pkgs.komorebi, pkgs.komorebic and pkgs.komorebi-bar individually)

flake.nix

{
  environment.systemPackages = [
    pkgs.komorebi-full
  ];
}

Building From Source

Make sure you have installed rustup, a stable Rust compiler toolchain, and if compiling on Windows, the Visual Studio Visual Studio prerequisites.

Clone the git repository, enter the directory, and build the following binaries:

Build and install the individual binaries

# Windows and macOS
cargo +stable install --path komorebi --locked
cargo +stable install --path komorebic --locked
cargo +stable install --path komorebi-bar --locked

# Windows only
cargo +stable install --path komorebi-shortcuts --locked
cargo +stable install --path komorebic-no-console --locked
cargo +stable install --path komorebi-gui --locked

The binaries will be installed to $HOME/.cargo/bin. It is your responsibility to ensure this directory is in your $PATH.

You can follow similar instructions to build whkd from source on Windows.

Offline Installation

Windows users can download the latest komorebi and whkd MSI installers on an internet-connected computer, then copy them to an offline machine to install.