Choose your install | Hypercolor

Not every install path is right for every person. This page routes you to the correct one before you spend time on the wrong steps.

Linux, Windows, and macOS are all supported install platforms. Linux additionally gets udev rules and a systemd user service. macOS supports screen capture and native host input, but it has no SMBus motherboard/DRAM RGB path. Screen-lock and suspend behavior works on all three platforms; the idle-dimming and laptop-lid settings are accepted but nothing emits those events yet.

#Decide in 30 seconds

I am…	My OS	Go here
A Debian or Ubuntu user	Linux	`.deb` package
A user on another distribution	Linux	Prebuilt one-liner and permissions
A regular user who wants things to work	Windows	Desktop installer
A regular user who wants things to work	macOS	DMG or Homebrew
An Arch Linux user	Linux	AUR package
A WLED or network lighting user with a server or NAS	Linux	Docker
A developer or contributor	Any	Build from source

If you are not sure whether you are a developer, you are not a developer. Start with the prebuilt path.

#Prebuilt one-liner (Linux)

The fastest path on Linux. Downloads the latest release binaries from GitHub, verifies them, installs them to ~/.local/bin, and sets up the systemd user service. It never asks for sudo, so the udev rules and the i2c-dev kernel module are left to you.

curl -fsSL https://raw.githubusercontent.com/hyperb1iss/hypercolor/main/scripts/install-release.sh | bash

No Rust toolchain required. The script is idempotent, so it is safe to re-run to upgrade.

Supported platforms: Linux x86_64 and aarch64. The installer also supports macOS on Apple silicon and refuses Intel Macs. Use the desktop app for the macOS setup flow.

#Installer options

Pass flags after -- to control the install:

# Pin any tagged release (replace vX.Y.Z with the tag)
curl -fsSL https://raw.githubusercontent.com/hyperb1iss/hypercolor/main/scripts/install-release.sh | bash -s -- --version vX.Y.Z

# Skip service setup (useful for custom init systems)
curl -fsSL https://raw.githubusercontent.com/hyperb1iss/hypercolor/main/scripts/install-release.sh | bash -s -- --no-service

# Skip the uninstall confirmation prompt
curl -fsSL https://raw.githubusercontent.com/hyperb1iss/hypercolor/main/scripts/install-release.sh | bash -s -- --uninstall --yes

# Remove Hypercolor
curl -fsSL https://raw.githubusercontent.com/hyperb1iss/hypercolor/main/scripts/install-release.sh | bash -s -- --uninstall

On macOS you can set HYPERCOLOR_INSTALL_PREFIX and HYPERCOLOR_INSTALL_DIR to move the install root. On Linux the prefix is fixed at ~/.local and the command directory at ~/.local/bin; the script refuses anything else. Releases and update state follow XDG_DATA_HOME and XDG_STATE_HOME as recorded by the first install.

#What the installer does

Detects your architecture and downloads the matching release tarball from GitHub.
Verifies the SHA256 checksum before extracting.
Installs the release under ~/.local/share/hypercolor/releases and links hypercolor, hypercolor-daemon, hypercolor-app, hypercolor-tui, and hypercolor-open into ~/.local/bin.
Installs the systemd user service to ~/.config/systemd/user/hypercolor.service, enables it, and proves the new daemon is healthy before it commits. A failed start restores the previous release.

How Linux release installs are managed covers the layout, upgrades from older installs, uninstall, and the directory permissions the installer requires.

The release tarball carries the udev rules and the i2c-dev modules-load config, but the one-liner never applies them because it never asks for sudo. Debian, Ubuntu, and Arch users can avoid the manual step by using the .deb or AUR package. Other distributions should follow the manual permissions steps after the one-liner finishes.

After the installer finishes, see First launch to open the UI for the first time.

#Windows installer

Download the installer from the download page and run it. The install is per-machine and asks for administrator elevation (UAC). The same elevated pass runs hardware setup: it installs the PawnIO SMBus modules and registers the HypercolorSmBus broker service. Windows builds are currently unsigned, so SmartScreen may warn on first run; choose “More info” and then “Run anyway”. Tested on Windows 10 22H2 and Windows 11 23H2/24H2, x64.

USB-HID lighting (Razer, Corsair, Lian Li, and others) and network devices (Hue, WLED, Nanoleaf, Govee) work out of the box. Native ASUS Aura motherboard and DRAM lighting uses the PawnIO hardware support installed above. MSI, Gigabyte, and other hardware without a native Hypercolor driver can use the separately installed OpenRGB bridge. If Hypercolor’s PawnIO setup was skipped or failed, re-run it from Settings → Device Discovery → Hardware Support.

#macOS

#DMG

Download Hypercolor-<version>-arm64.dmg from the download page, drag the app into /Applications, and launch. Hypercolor for macOS requires Apple silicon and macOS 15.2 (Sequoia) or newer; Intel Macs are not supported.

Hypercolor requests Screen Recording permission when you enable screen capture. For system audio, follow Audio setup.

#Homebrew

Install the desktop app for the full setup and permissions UI, or choose the formula for a daemon managed by brew services.

# Desktop app
brew install --cask hyperb1iss/tap/hypercolor-app

# Daemon and CLI
brew install hyperb1iss/tap/hypercolor

The formula covers macOS arm64 plus Linux amd64 and arm64. The cask is the full desktop app for Apple silicon. On Intel Macs, Homebrew refuses both the formula and the cask.

The formula selects the Homebrew service topology when managed with brew services. Install the cask when protected macOS permissions or the system screen picker require the app UI.

#AUR (Arch Linux)

The hypercolor-bin package is live on the AUR and updates automatically on every tagged release:

yay -S hypercolor-bin

The AUR package installs the prebuilt binaries, sets up the systemd user service, and places both udev rules files in the correct system paths.

#Build from source

Building from source is the right path for contributors, packagers, and people who need a custom build (e.g., with Servo HTML effect rendering enabled). It is not necessary for end users.

You need:

Rust 1.95+ (Edition 2024), installed via rustup
just, the task runner
System libraries for your OS (USB, audio, GTK, WebKit)

git clone https://github.com/hyperb1iss/hypercolor.git
cd hypercolor
cargo install just
just setup
just install

just setup bootstraps the Rust toolchain, system packages, Bun, Trunk, cargo-deny, and frontend dependencies. It detects your Linux distribution (Debian/Ubuntu, Fedora, Arch) and uses the right package manager. It is idempotent, so it is safe to re-run.

just install builds the daemon, CLI, and web UI at release profile, installs binaries to ~/.local/bin, enables the systemd user service, installs udev rules, and persists i2c-dev.

Full system dependency lists and optional flags (--minimal, --no-system, --with-servo) are in the Installation reference.

On Linux, the source and prebuilt paths both install Hypercolor under ~/.local and use the same systemd user service. A source install applies the USB rule and i2c-dev setup; run just udev-install from the checkout to add the input capture rule too. The prebuilt one-liner leaves every system hook to the separate permissions step above.

#Release notifications

The standalone OSS daemon checks GitHub for a newer stable release at startup when its cached check is older than a day, then checks daily while running. Failed checks retry after 15 minutes. An available release appears in a banner; release notes are available in Settings or on GitHub.

Open Settings → System → About → Updates to check manually, turn automatic checks off, or skip a release. Downloading opens the published asset for the machine running the daemon. Run the Windows installer or open the macOS DMG to complete a desktop upgrade. If you installed through Homebrew, AUR, or another package manager, update through that same package manager. Linux release-installer users can rerun the prebuilt installer.

#After installing

Whichever path you took, your next stop is First launch, which walks through the first-run wizard, device discovery, and opening the web UI for the first time.

If a USB device does not appear after install, the most common cause is udev rules not applied yet. Re-plug the device or log out and back in. The Quick start covers this and has a one-command health check.