Skip to content

macOS Installation

Jump to bottom
Le Khanh Binh edited this page Jul 4, 2026 · 1 revision

macOS Installation

ZenTune on macOS is for Hackintosh systems with an AMD Ryzen CPU. There's no /sys or raw PCI config file on macOS, so the daemon reaches the SMU through the DirectHW kernel extension, or a kext-free fallback through IOKit's IOPCIBridge service. Adaptive Mode is not available on macOS yet; everything else (presets, Custom Preset Editor, Automations, the reapply loop) works the same as on Linux.

1. System requirements

  • macOS on a Hackintosh with an AMD Ryzen APU or desktop CPU. Intel is not supported.
  • Python 3.10 or newer. Check with python3 --version.
  • Root access (sudo). The IOKit user client that reaches the SMU only opens for uid 0.
  • Either:
    • DirectHW kext loaded, and SIP set to allow kexts (csr-active-config = 03080000 on a typical Hackintosh), or
    • The kext-free fallback: no kext needed, but requires the debug=0x144 boot-arg. This path reaches config space only, so the PM table (used for live sensor graphs) isn't available through it; tuning still works.

2. Set up DirectHW (recommended path)

DirectHW gives you the full feature set, including the Home tab's live sensor graphs.

  1. Install DirectHW's kext following the project's own instructions.
  2. Confirm SIP allows kexts. Check your current value: 
    nvram csr-active-config
    If it's not %00%08%00%00 (03080000), adjust it in your bootloader's SIP settings (OpenCore's config.plist, csr-active-config) and reboot.
  3. Confirm the kext is loaded: 
    kextstat | grep DirectHW

If DirectHW is loaded, ZenTune uses it automatically. No extra flags needed.

3. Or use the kext-free fallback

If you don't want to install a kext, ZenTune can reach config space through macOS's built-in IOPCIBridge service instead. This needs a boot-arg:

  1. Add debug=0x144 to your boot-args (in OpenCore's config.plist under NVRAM -> boot-args, alongside anything already there).
  2. Reboot.
  3. Verify: 
    sysctl kern.bootargs
    Should include debug=0x144.

With that boot-arg set, ZenTune falls back to this path automatically when DirectHW isn't loaded.

Trade-off: this path can't map physical memory, so the PM table is unavailable, meaning the Home tab's live sensor graphs won't show data. Tuning (presets, Custom Preset Editor, Automations) works normally either way.

4. Install ZenTune

curl -fsSL https://raw.githubusercontent.com/HorizonUnix/ZenTune/main/install.sh | bash

Run as your normal user, not root. The script asks for sudo only where it's needed. It detects macOS automatically and:

  • Installs unzip and curl if missing (both usually already present on macOS)
  • Downloads the latest release to /opt/zentune/src/
  • Creates a venv at /opt/zentune/venv/ with pyzmq, textual, textual-plotext and zenmaster
  • Creates the launcher at /usr/local/bin/zentune
  • On update: replaces app files, restarts the daemon, keeps your config.ini and custom.json

The launchd service is set up by the first-run wizard, not the installer.

Prefer not to curl a script into bash? Clone the repo and run the same installer locally instead:

git clone https://github.com/HorizonUnix/ZenTune.git
cd ZenTune
./install.sh --local

5. First run

zentune

The setup wizard walks you through the same three steps as on Linux: welcome, background daemon (installs a launchd daemon under com.horizonunix.zentune instead of a systemd unit), then hardware detection. See Linux Installation, step 4, for what each step looks like; the flow is identical, only the underlying service manager differs.

Because Adaptive Mode isn't available on macOS yet, that tab and its Settings toggle are hidden automatically, everything else in the interface is the same as on Linux.

6. Updating

Same as Linux: the app checks GitHub on launch and offers an update, or force one from About (?) -> Check updates. Re-running the install script works too.

7. Uninstalling

Run the install script with --uninstall:

curl -fsSL https://raw.githubusercontent.com/HorizonUnix/ZenTune/main/install.sh | bash -s -- --uninstall

Removes:

Item Path
launchd service (if present) /Library/LaunchDaemons/com.horizonunix.zentune.plist
Launcher /usr/local/bin/zentune
App, venv and config /opt/zentune
Runtime socket / lock /var/run/zentune.sock, /var/run/zentune_daemon.lock
TUI lock /tmp/zentune_tui.lock

To skip the confirmation prompt, set ZENTUNE_ASSUME_YES=1 the same way as on Linux.

Report an issue · Releases

Home

Getting started

Using the app

Internals

Clone this wiki locally