Installation

Installation

ZenMaster installs from PyPI with pip on Linux, Windows, and macOS. The package itself has no mandatory third-party dependencies on any of them. What differs between platforms is how the SMU is reached: a kernel module or PCI access on Linux, the PawnIO driver on Windows, DirectHW.kext (or a kext-free fallback) on macOS.

pip install zenmaster

Upgrade later with:

pip install -U zenmaster

Check what is installed and whether a newer release exists:

zenmaster --version

---

Linux

Requires root, and either the ryzen_smu kernel module or PCI direct access. ZenMaster picks whichever is available automatically.

pip install zenmaster
sudo zenmaster --stapm-limit=15000 --fast-limit=20000 --tctl-temp=90

Which backend will I use?

ZenMaster picks the backend strictly by Secure Boot state:

Secure Boot OFF  →  PCI direct access (no kernel module needed)
Secure Boot ON   →  ryzen_smu module (kernel lockdown blocks PCI)

With Secure Boot off, ZenMaster always uses PCI direct access, probing the northbridge config registers with a round-trip write. With Secure Boot on, raw PCI access is blocked by kernel lockdown, so the ryzen_smu module is required.

Confirm which backend is active:

sudo zenmaster --info

Name   : AMD Ryzen 7 7840U
Family : PhoenixPoint  (Zen 3 - Zen 4)
Type   : Amd_Apu
Socket : FT6_FP7_FP8
Backend: pci

Installing ryzen_smu (only needed with Secure Boot)

git clone https://github.com/amkillam/ryzen_smu
cd ryzen_smu && make && sudo make install
sudo modprobe ryzen_smu

ZenMaster needs ryzen_smu 0.1.7 or newer (it uses the /smn interface). With Secure Boot on, you must also sign the module with a MOK key and enroll it, or disable Secure Boot in UEFI.

pip install as root vs. user

The SMU writes need root, so run the zenmaster command with sudo. If you installed into a user environment, sudo zenmaster may not find it on PATH; in that case run it as a module:

sudo python3 -m zenmaster --info

or install system-wide:

sudo pip install zenmaster

---

Windows

ZenMaster reaches the SMU through PawnIO, a Microsoft-signed kernel driver. It replaces WinRing0 (used by RyzenAdj), which has known CVEs.

1. Download and run the PawnIO installer: https://github.com/namazso/PawnIO.Setup/releases/latest/download/PawnIO_setup.exe
2. Reboot so the driver activates.
3. Open an Administrator terminal (PowerShell or Command Prompt).

pip install zenmaster
zenmaster --stapm-limit=15000 --fast-limit=20000 --tctl-temp=90

ZenMaster bundles the RyzenSMU.bin PawnIO module it needs, so the only thing you install yourself is the PawnIO driver.

All SMU operations on Windows require Administrator. If PawnIO is not installed or the terminal is not elevated, ZenMaster exits early with a message telling you which.

---

macOS (AMD Hackintosh)

This only applies to a Hackintosh: real Macs don't run AMD CPUs. ZenMaster detects the chip straight off CPUID via sysctlbyname, which is why it works even when OpenCore has SMBIOS set to report a real Mac model; CPUID isn't something SMBIOS spoofing touches.

Requires root, and one of two access paths:

• DirectHW.kext: the full path, including --table/--sensors. Needs the kext loaded, and SIP configured to allow unsigned kexts on a Hackintosh (csr-active-config=03080000 in Clover/OpenCore).
• Kext-free fallback (--iopci): no kext needed, but tuning only, no PM table. Needs the debug=0x144 boot-arg set.

pip3 install zenmaster
sudo python3 -m zenmaster --stapm-limit=15000 --fast-limit=20000 --tctl-temp=90

If neither access path is set up, ZenMaster's error message tells you which one to add and how.

sudo zenmaster can fail with "command not found" if the zenmaster script lands somewhere root's PATH doesn't reach, common with pip3 install --user or a Homebrew Python. sudo python3 -m zenmaster sidesteps that by going straight through the interpreter instead of relying on PATH.

To force the kext-free path even when DirectHW is installed (useful for testing without the kext):

sudo zenmaster --iopci --info

See How ZenMaster Talks to the SMU for why macOS needs two different paths at all, and what each one can and can't do.

---

Verifying the install

A quick, non-destructive check that everything is wired up:

# Linux
sudo zenmaster --info

# Windows (Administrator)
zenmaster --info

# macOS
sudo python3 -m zenmaster --info

If detection and the backend look right, you are ready. See CLI Usage next, or Tuning Arguments for what you can actually set.

If anything fails here, go to Troubleshooting.