Installation

Requirements

• macOS 26+ (Tahoe) on Apple Silicon
• Accessibility and Input Monitoring permissions (required at launch)
• Screen Recording permission for Overview thumbnails, rendered wallpaper previews, drag previews, and captured Hidden Bar glyphs (optional)
• Full Disk Access permission for Hidden Bar concealment (optional)
• Displays have separate Spaces ON (the macOS default; OmniWM pauses window management until it is enabled)

Homebrew

OmniWM is in the official Homebrew cask repository:

brew install --cask omniwm

This installs OmniWM.app and puts omniwmctl on your PATH. Then finish with the first-launch setup below.

Upgrading

Quit OmniWM first, then run brew upgrade omniwm and relaunch it. Homebrew replaces the app bundle underneath a running OmniWM.

Migrating from the project tap

BarutSRB/tap is retired: 0.6.7 was its final release, and every later version ships only through the official cask. If you installed from the tap, quit OmniWM and run these commands in this order:

brew update
brew upgrade omniwm
brew untap BarutSRB/tap

brew update has to come first: it fetches the retired tap’s redirect to the official cask and moves your install over. Untapping before that would offer to uninstall OmniWM. brew reinstall --cask homebrew/cask/omniwm is optional and only switches the install record to the official cask right away.

Nix

OmniWM is packaged in nixpkgs, maintained by mmfallacy and samiser, and Home Manager ships an official programs.omniwm module, maintained by DavSanchez. The package installs the signed release artifact with bsdtar, so the Developer ID signature stays valid, and exposes OmniWM and omniwmctl on PATH. Both currently live on unstable branches only (the nixpkgs unstable channels and Home Manager master) and may trail the latest GitHub release.

Install the package directly:

nix profile install nixpkgs#omniwm

With nix-darwin or Home Manager, add pkgs.omniwm to environment.systemPackages or home.packages.

For a declarative setup, enable the Home Manager module. It installs the package, runs OmniWM as a launchd agent, and writes ~/.config/omniwm/settings.toml from an attribute set or a tracked TOML file:

programs.omniwm = {
  enable = true;
  settings = ./omniwm-settings.toml;
};

Treat the declared TOML file or attribute set as authoritative: edit it and run Home Manager switch to apply changes. OmniWM preserves settings symlinks, so settings backed by a read-only Nix-store file cannot be saved from the GUI.

Home Manager enables a launchd agent with KeepAlive by default. To launch and quit OmniWM manually instead, set programs.omniwm.launchd.enable = false.

After either installation, finish with the first-launch setup below.

GitHub Releases

1. Download the OmniWM-v<version>.zip app archive from the latest release.
2. Extract and move OmniWM.app to /Applications.
3. Continue with the first-launch setup.

First-launch setup

1. In System Settings > Desktop & Dock > Mission Control, turn ON Displays have separate Spaces.
2. Log out of macOS and log back in for that change to take effect, unless you had it on already.
3. Launch OmniWM and grant Accessibility and Input Monitoring when prompted. Both are required at launch.
4. Optionally grant Screen Recording for capture-derived visuals: Overview thumbnails, rendered wallpaper previews, drag previews, and captured Hidden Bar glyphs.
5. Return to OmniWM’s permissions window and click Start OmniWM or Continue Without Screen Recording. If a required permission still appears missing, click Check Again.

Note

An optional System Hyper Trigger (acting as the Hyper chord while a key or mouse button is held) also needs the Input Monitoring permission. See Keyboard Shortcuts.

Canary builds

Stable releases are recommended for everyday use. Canary builds let you try recent changes and help test fixes before the next release. They are built daily when main has new changes and are signed and notarized, but may contain regressions.

To try one with a Homebrew or GitHub Releases install:

1. Save a copy of ~/.config/omniwm/settings.toml.
2. Quit OmniWM, then download the newest canary build and replace OmniWM.app in /Applications with the app from its ZIP.
3. Relaunch OmniWM. It uses your existing settings.

OmniWM’s update check only tracks stable releases, so download newer canaries the same way. To return to stable, quit OmniWM. For a Homebrew install, run brew reinstall --cask omniwm; for a direct download, replace the app with the latest release. If stable cannot read settings saved by a canary, quit OmniWM and restore your copy. When reporting a canary bug, include its release link.

Updates

OmniWM checks for updates by default:

• On launch, OmniWM polls the latest GitHub release at most once per day.
• Updates stay manual. OmniWM does not auto-download or auto-install a new release.
• When a newer release is available, OmniWM shows a centered popup with release notes and actions for Open Release Page, Copy brew upgrade omniwm, Skip This Version, and Not Now.
• You can control this from Settings > General > Updates or trigger a manual check from the status bar menu with Check for Updates....