Applies to: FanControl 1.5.0
中文版见
移植说明.md.
| Condition | Requirement | If not met |
|---|---|---|
| 1. It must be a hackintosh | You can edit OpenCore's config.plist |
A real Mac won't load a third-party kext — the whole approach is impossible |
| 2. The Super I/O chip must be Nuvoton NCT679x | NCT6790D…NCT6798D, NCT679BD, or NCT6779D |
Other chips (ITE, Winbond, NCT6776D, …) are unsupported |
| 3. It must be an Intel machine | The kext is built for x86_64 | It cannot load on Apple Silicon |
All three met → it works. Run the self-check once after installing to confirm:
zsh /usr/local/sbin/fancontrol-checkIt checks each item and prints a verdict at the end.
By the way: if that machine is a real Mac (not a hackintosh), don't use this — real Macs can control their fans with off-the-shelf software like Macs Fan Control, and injecting a kext there is neither needed nor permitted.
The userspace programs (the GUI, fanctl, gpufand) are compiled for a macOS 13.0 target,
so they run as-is on macOS 15, and they are built as x86_64 + arm64 universal binaries.
On the kext side:
- This package is based on VirtualSMC 1.3.8 + Lilu 1.7.2; both support macOS 15.
- Since macOS 11, third-party kexts can only be injected through OpenCore — you can no longer
drop them into
/Library/Extensions(they won't load, and you'll get a "system extension blocked" prompt). - The kext's
OSBundleLibrariesrequiresVirtualSMC >= 1.0.0andLilu >= 1.2.0, so the VirtualSMC and Lilu in your EFI can't be too old.
There is no difference between macOS 15 and macOS 26 for this approach — the same kext and the same configuration work on both.
The installer places the Nuvoton-write-capable kext at:
/usr/local/share/fancontrol/SMCSuperIO.kext
(This kext has the same name and the same bundle id ru.joedm.SMCSuperIO as the SMCSuperIO
already in your EFI — it merely adds write access for Nuvoton NCT679x.
Replace the file; don't keep both.)
Steps:
-
Mount the EFI partition. Find which EFI contains
EFI/OC/OpenCore.efi:diskutil list # find the EFI partition (usually 200MB) sudo diskutil mount diskXs1 -
Back up the original first:
cd /Volumes/EFI/EFI/OC/Kexts cp -R SMCSuperIO.kext SMCSuperIO.kext.bak-$(date +%Y%m%d)
-
Replace it:
rm -rf SMCSuperIO.kext cp -R /usr/local/share/fancontrol/SMCSuperIO.kext . -
Edit
EFI/OC/config.plistand, underKernel → Add, make sure this entry exists and the order is right:SMCSuperIO.kextmust come afterVirtualSMC.kext(a dependency must precede its dependant)- Also confirm
Lilu.kextcomes beforeVirtualSMC.kext
⚠️ OpenCore injects in order. An entry whose dependency isn't in place yet is silently skipped — no error, not even a load attempt in the log. This is the easiest trap to fall into. -
Reboot.
Every machine numbers its fan channels differently. The built-in default is ch6 (this author's ASUS layout). You must re-check it on a different machine, or you might put a real water-cooling pump under ordinary fan control — throttling the pump starves the loop of coolant flow.
How to check (read-only, safe):
- Open FanControl, let the machine idle for a few minutes, and watch the live RPM of each channel in the "Fan channels" table.
- The channel whose speed is clearly high, nearly constant, and doesn't track CPU temperature is the pump. (On this machine that's ch6 / AUXFAN4 at ≈2800 RPM; every other fan sits at 400–900.)
- Cross-check: run a stress load. Channels that rise with it are fans; the one that doesn't move is the pump.
⚠️ Do not usegpufan scanto test this — it drives every channel to 100% and back down to 0%, including the pump.
Once confirmed, write it into the config:
sudo sh -c 'echo pump_channel = <channel> >> /usr/local/etc/fancontrol.conf'
sudo launchctl kickstart -k system/com.shohart.gpufandUntil that config exists, the GUI shows an orange warning above "Fan channels".
sudo installer -pkg FanControl-1.5.0.pkg -target /Or double-click the .pkg. Note: this package has no Apple Developer signature — if double-clicking
says "cannot be opened because it is from an unidentified developer":
- Right-click → Open → Open again, or
- System Settings → Privacy & Security → click "Open Anyway" at the bottom, or
- Just use the
installercommand above.
cd FanControl
zsh build.sh # build
sudo zsh install.sh # install| Path | Description |
|---|---|
/Applications/FanControl.app |
The GUI (x86_64 + arm64 universal), with a custom icon; stays in the menu bar while running |
/usr/local/sbin/fanctl |
The privileged helper — the only thing that writes to SMC |
/usr/local/sbin/gpufand |
The temperature → duty-cycle daemon |
/usr/local/sbin/fancontrol-check |
Compatibility self-check script |
/Library/LaunchDaemons/com.shohart.gpufand.plist |
The launch daemon (starts at boot) |
/usr/local/etc/gpufand.conf |
Temperature-curve configuration |
/usr/local/etc/fancontrol.conf |
Per-machine settings (the pump channel) |
/etc/sudoers.d/fancontrol |
Passwordless rule — authorizes only the five fanctl subcommands |
/usr/local/share/fancontrol/ |
The kext, default config, this guide, and the uninstall script |
-
The
gpufanddaemon: yes, it starts at boot.RunAtLoad = true, so the mode you picked (Silent / Standard / Performance / …) is restored automatically after a reboot. -
The
FanControl.appGUI: since 1.4.1 you can enable "Start at login" from the menu-bar panel.It uses the system's login-item mechanism (
SMAppService), so you can see it — and turn it off — under System Settings → General → Login Items.After boot it opens the main window automatically; just close it — the menu-bar icon stays.
If you don't want a window popping up at boot, leave this switch off. Speed control itself is done by
gpufand; the GUI is only needed when you want to change settings.
The top of the left column has two tabs: Control / Monitor. The Monitor page has 8 panels you can toggle independently:
| Panel | Contents | Data source |
|---|---|---|
| CPU | Total usage, user/system split, load, history graph, per-core usage | host_processor_info |
| GPU | Fan RPM / temperature / power / clocks / utilization | IOAccelerator in IORegistry |
| Memory | Used/total, wired, compressed, swap | host_statistics64 + sysctl |
| Storage | Used space per volume | getmntinfo |
| Network | Up/down throughput (measured on a 2-second poll) | sysctl NET_RT_IFLIST2 |
| Processes | Top 10 processes by CPU | Two libproc samples, differenced |
| Sensors | CPU 8 cores + GPU temperature | SMC |
| System | CPU model, logical cores, uptime, load | sysctl |
Toggles are remembered in preferences and restored next launch; there's also a
"Show all / Hide all" switch. Everything is read-only, needs no root, and writes nothing.
It's implemented in the fanctl sys subcommand, so you can also run it in a terminal:
/usr/local/sbin/fanctl sysOn CPU power: this machine is Intel, and the
IOReport"Energy Model" group doesn't exist on Intel (it's Apple Silicon only), so there is no CPU power panel. GPU power is visible in the "GPU" panel.
While running, the app lives in the right side of the menu bar, showing "fan icon + CPU temperature + GPU temperature" by default. Click it for a panel; the lower half has 8 switches — turn on whichever you want to see:
| Item | Shows |
|---|---|
| Fan icon | Just an icon, no number |
| CPU temperature | Hottest CPU core |
| GPU temperature | GPU temperature (from SMC's RadeonSensor) |
| CPU usage | Total utilization |
| Memory | Used percentage |
| Fan RPM | Fastest of the controlled fans (excluding the pump) |
| GPU fan | The GPU's own fan RPM |
| Network | Downlink rate (compact, e.g. 1.2M) |
Toggles are remembered in preferences (fancontrol.menuBarItems) and restored next launch.
Each menu-bar item carries its own icon, so they're easy to tell apart.
At the bottom of the panel are three buttons: Open main window / Refresh now / Quit.
A few things to note:
- Closing the main window ≠ quitting. The menu-bar icon stays; click "Open main window" or the Dock icon to bring it back. To really quit, use the power button in the panel or ⌘Q.
- If all 8 items are off, a single fan icon remains — otherwise the menu bar would become unclickable and the settings unreachable forever.
- All of this is read-only sampling: it writes nothing and needs no extra privileges.
Implementation note (for anyone modifying the code): the menu-bar items do not use SwiftUI's
MenuBarExtra. In practice its label only takes the firstImageas the button icon and the firstTextas the title, silently discarding the rest (HStack+ForEach, concatenated Text,.fixedSize(), andLabelwere all tried). Since "multiple items each with an icon and a value" isn't expressible that way, the app uses AppKit'sNSStatusIteminstead, drawing the SF Symbol and the text together viaattributedTitle+NSTextAttachment. The code is inapp/StatusItem.swift.
The "GPU" panel shows the graphics card's fan RPM / duty / temperature / power / core clock /
utilization. The data comes from the IOAccelerator node in IORegistry; read-only, no root.
Why it can't be controlled:
GPU fans are managed jointly by the card's firmware PowerPlay table and the GPU driver. macOS exposes no public write interface, and there's no ADL / Afterburner-style tool. Writing the card's I2C directly, bypassing the driver, just gets overwritten by the driver and risks damaging the card.
If you really want to change it, there's exactly one route — edit the curve statically:
Injecting PP_PhmSoftPowerPlayTable (a soft PowerPlay table) into the card via OpenCore's
DeviceProperties lets you change the fan curve / disable Zero RPM / change the start temperature.
It takes effect on reboot and affects macOS only (Windows uses its own driver).
Reference implementation: perez987/RX6600XT-on-macOS-with-softPowerPlayTable;
tool: olarila's ZeroRPMBuilder for macOS. If you break something, delete that DeviceProperties
entry to roll back.
Notes:
- A GPU with no driver (e.g. NVIDIA 20/30-series under macOS) doesn't show this panel — there's no node in IORegistry at all, so nothing can be read.
- The panel's "temperature" comes from IORegistry; the GPU temperature in "Temperature source" on the
left comes from SMC (
TG0D/TG0P, provided by the RadeonSensor kext). They usually agree but serve different purposes: the former is display only, the latter is the one that actually feeds the fan curve. - Case fans are in fact already tracking GPU temperature —
source = TG0D,TG0Pingpufand.confis the GPU temperature, and with multiple sources the one demanding the highest duty wins. So when the GPU heats up, case fans speed up on their own.
sudo zsh /usr/local/share/fancontrol/uninstall.shThis hands all fans back to the BIOS, then removes the daemon, helper, sudoers rule, and GUI.
(The kext and this guide under /usr/local/share/fancontrol/ are kept — delete them by hand if you want.)
To revoke only the privilege escalation, without uninstalling:
sudo rm -f /etc/sudoers.d/fancontrolQ: fancontrol-check says SMC has no F<n>Md keys, so fans can't be controlled.
That means the write-capable SMCSuperIO isn't loaded. Check, in order:
- Is the
SMCSuperIO.kextin your EFI the one this package provides (you canstringsit and look forNuvoton NCT679)? - Is it registered under
config.plist → Kernel → Add, withEnabledset totrue? - Does it come after
VirtualSMC.kext? - Is the chip model on the whitelist (
ioreg -l -w0 | grep ChipName)?
Q: The GUI opens, but "Apply" reports a permission error.
The username in /etc/sudoers.d/fancontrol was written at install time from whoever was logged in then.
If you've changed accounts, re-run the installer, or edit the username in that file by hand.
Q: A fan stops at 0% and won't come back.
Some fans stall below a certain duty and don't restart on their own. Raise the "Minimum duty" slider to 15–25% and click Apply; or click "Hand back to BIOS" and let the motherboard take over.
Q: GPU temperature doesn't show.
That's an ordering issue between the RadeonSensor and SMCRadeonGPU kexts — SMCRadeonGPU depends
on RadeonSensor and must come after it. Nothing to do with this app.
Q: The GPU panel is missing entirely, or an item shows "—".
The 1.2 GPU monitoring only works for GPUs that have a driver:
- Panel missing entirely → there's no
IOAcceleratornode with fan data inIORegistry. Typical case: a GPU with no driver (NVIDIA 20/30-series under macOS). - One item shows "—" → this card doesn't expose that field; different cards expose different fields.
- Everything shows "—" → this card provides none of these statistics.
To see the raw data (read-only, no root):
/usr/local/sbin/fanctl gpuA healthy run looks like:
{"ok":true,"gpu":{"fanRPM":521,"fanPercent":14.0,"temp":49,"power":46.0,
"coreClock":221,"memClock":2300,"utilization":3}}Q: I have Macs Fan Control / TG Pro — will they conflict?
No. They and gpufand all operate through the same SMC keys, and whoever writes last wins.
(In fact, now that writable F<n>Tg/F<n>Md keys exist in SMC, Macs Fan Control might be able to
control the fans too — worth a try.)
Q: I can't find the FanControl icon in the menu bar.
First confirm the app is running (is its icon in the Dock?). The menu-bar item only exists while the app runs. Since 1.4.1 you can turn on "Start at login" from the menu-bar panel (via system login items), but it's off by default — if you never enabled it, you'll need to open the app yourself after a reboot.
If the app is running but there's no menu-bar item: the menu bar is too crowded and the system hid it. Since macOS 13, items that don't fit are hidden automatically. Close a few other menu-bar utilities, or reduce the displayed items to 2–3.
Q: The numbers in the menu bar don't match the main window.
The menu bar refreshes every 2 seconds, and the main window refreshes in sync, but a screenshot or a glance always lands slightly before or after. Also, "Fan RPM" in the menu bar is the fastest of the controlled fans (excluding the pump), whereas the fan list in the main window shows each channel's own value.
Q: After closing the main window the app is still there — didn't it quit cleanly?
That's intentional — closing the window just hides it; the menu-bar icon stays. To really quit: click the menu-bar icon → the power button at the bottom-right of the panel, or press ⌘Q.