Install

System requirements

• macOS 12.3+, Windows 10+, or a mainstream Linux desktop (GNOME, KDE, XFCE). On Linux you also need GTK 3, WebKitGTK 4.1, and libudev; the AppImage bundles X11 capture deps (libxcb, libxrandr, libpipewire, libdbus).
• At least one supported hardware target, otherwise the app runs but nothing lights up:
  • A Philips Hue Bridge (gen 2 or newer, including the 2025 Bridge Pro from v1.5.4) with one or more Entertainment Areas configured in the Hue app, or
  • A WS2812B / SK6812 RGBW LED strip driven by a supported USB-serial controller (CH340, CH341, FT232, PL2303, or CP2104) running LumaSync v1 firmware or the opt-in Adalight profile, or
  • An ESP32 / ESP8266 board running WLED firmware on the same LAN as the host machine — see the WLED bridge page.
• See Hardware checklist for a parts list if you’re starting from scratch.

macOS

Download the universal .dmg from the Download page or the latest GitHub release. Apple Silicon and Intel Macs are covered by the same installer.

1. Open the .dmg and drag LumaSync.app into Applications.

2. The first launch will be blocked. LumaSync is not notarized by Apple, so macOS refuses to open it and shows “Apple could not verify ‘LumaSync’ is free of malware.” This is expected, and clearing it takes four steps:

   • Try to open LumaSync. Click Done on the warning.
   • Open System Settings → Privacy & Security and scroll to the Security section.
   • You will see “LumaSync was blocked to protect your Mac.” Click Open Anyway.
   • Confirm with Touch ID or your password, then click Open on the final prompt.

   You only do this once. On macOS Sequoia (15) and later, Control-clicking the app and choosing Open no longer works — Apple removed that shortcut, so ignore any guide that still recommends it. If you would rather verify the download yourself first, see Verification below.

3. Next, macOS asks for Screen Recording permission so the ambilight pipeline can sample your display. Grant it — without it the ambient mode has nothing to read from.

4. LumaSync starts hidden to the tray; click the menu-bar icon to open the main window. Cmd+Q from anywhere shuts the app down cleanly via the watchdog-bounded shutdown path; closing the window only hides it to the tray.

Updating from 1.5.2 on macOS? The 1.5.2 macOS build could crash on launch on Macs without Xcode installed (dyld: Library not loaded: @rpath/libswift_Concurrency.dylib). v1.5.3 fixes it — the Swift concurrency runtime now links against the system library that ships with macOS, so no Xcode or developer tools are needed, and a release-pipeline guard prevents the regression from recurring. If you were stuck on 1.5.2, reinstall from the Download page.

Windows

Download the .msi installer from the Download page. It runs a typical “Next, Next, Finish” dialog and installs to C:\Program Files\LumaSync\. From v1.5.1 every release ships the MSI alongside the macOS DMG and Linux packages — no more platform gaps between releases.

Windows will warn you before it runs. LumaSync does not carry a Windows code-signing certificate, so SmartScreen shows “Windows protected your PC — unknown publisher.” Click More info, then Run anyway. If your machine has Smart App Control enabled, it blocks unsigned installers outright with no override; you would need to turn it off in Windows Security to install, which is your call to make.

Note that the “signed” you see mentioned around LumaSync releases refers to minisign, which is how the updater verifies a download before replacing anything on disk. That is a different thing from a Windows Authenticode signature, and it does not affect the SmartScreen prompt.

Linux

Three packages ship every release: .AppImage (distro-agnostic), .deb (Debian / Ubuntu), and .rpm (Fedora / openSUSE). Pick whichever your distro prefers.

# AppImage
chmod +x LumaSync_{LATEST_VERSION_BARE}_amd64.AppImage
./LumaSync_{LATEST_VERSION_BARE}_amd64.AppImage

# Debian / Ubuntu
sudo apt install ./lumasync_{LATEST_VERSION_BARE}_amd64.deb

# Fedora / openSUSE
sudo rpm -i lumasync-{LATEST_VERSION_BARE}.x86_64.rpm

Screen capture uses xcap for native X11 sampling — Wayland sessions need the X11 fallback (XWayland) for now. Tray behaviour varies by desktop environment: GNOME requires a third-party extension like AppIndicator Support to show the LumaSync tray icon; KDE Plasma and XFCE work out of the box.

Verification

Every release asset is signed with minisign. The public key is embedded in the app and the updater verifies every binary before replacing anything on disk. To verify a download manually:

minisign -Vm LumaSync_{LATEST_VERSION_BARE}_universal.dmg -P "$(cat minisign.pub)"

minisign.pub is committed to the app repo. See Auto-updater for how this works in-app.

Next steps

Once installed, continue to First setup to pair your Hue bridge or connect a USB controller, then pick your first mode.