Skip to content

Linux Installation

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

Linux Installation

1. System requirements

Before you start, make sure you have:

  • Linux. systemd is recommended, the setup wizard installs and manages the daemon as a service. Without systemd (OpenRC, runit, s6, etc.) the installer still works; it prints the manual daemon start command at the end and you run it yourself.
  • Python 3.10 or newer. Most distros from 2022 onward ship this. Check with python3 --version. The install script can install it for you if it's missing.
  • Root / sudo access, needed for the daemon service and the kernel module.
  • An AMD Ryzen APU or desktop CPU. Intel is not supported. If you're not sure whether your CPU is supported, install the app and run it; hardware detection will tell you.
  • A terminal at least 50x25 characters. The app shows a "terminal too small" notice below that size.

The Python dependencies are pyzmq, textual, textual-plotext and zenmaster (the cross-platform SMU backend library); the installer puts them all in a private virtual environment (/opt/zentune/venv), so they never touch your system Python.

2. Install ryzen_smu (Secure Boot only)

Note

Skip this section if Secure Boot is off. Check first:

mokutil --sb-state

SecureBoot disabled -> skip to step 3. SecureBoot enabled -> continue here.

Secure Boot on means the kernel blocks unsigned modules and raw PCI config writes. The daemon needs ryzen_smu to reach the SMU. Minimum version is 0.1.7.

2.1 Install build dependencies

You need cmake, gcc, g++ (or gcc-c++), dkms and openssl. DKMS rebuilds the module automatically on kernel updates.

Debian / Ubuntu / Linux Mint / Pop!_OS:

sudo apt update
sudo apt install cmake gcc g++ dkms openssl

Fedora:

sudo dnf install cmake gcc gcc-c++ dkms openssl

AlmaLinux / Rocky Linux 9:

sudo dnf install epel-release
sudo dnf install cmake gcc gcc-c++ dkms openssl

DKMS lives in EPEL on RHEL-based systems, so epel-release has to go in first. On RHEL itself you also need the CodeReady Builder repo enabled through subscription-manager.

CentOS Stream 9:

sudo dnf config-manager --set-enabled crb
sudo dnf install epel-release
sudo dnf install cmake gcc gcc-c++ dkms openssl

Arch Linux / Manjaro / EndeavourOS:

sudo pacman -S cmake gcc dkms openssl

openSUSE Tumbleweed / Leap:

sudo zypper install cmake gcc gcc-c++ dkms openssl

Void Linux:

sudo xbps-install -S cmake gcc dkms openssl

Gentoo:

sudo emerge --ask dev-build/cmake sys-kernel/dkms dev-libs/openssl

2.2 Build and install ryzen_smu

For more information, visit ryzen_smu.

git clone https://github.com/amkillam/ryzen_smu
cd ryzen_smu
sudo make dkms-install

Registers with DKMS and builds for your running kernel.

Verify:

sudo modprobe ryzen_smu
lsmod | grep ryzen_smu

ryzen_smu should appear in the output. If modprobe fails with "Operation not permitted" or a signature error, go to the Secure Boot section below.

2.3 Secure Boot

If Secure Boot is on, the kernel won't load unsigned modules. You need to enroll the DKMS signing key that was created during make dkms-install.

Enroll the key:

sudo mokutil --import /var/lib/dkms/mok.pub

Set a one-time password when prompted. You'll type it on the next boot.

Reboot:

sudo reboot

A blue MOK Manager screen appears on boot, it only stays for a few seconds, so watch for it:

  1. Enroll MOK
  2. Continue
  3. Yes
  4. Type the one-time password
  5. Reboot

After booting, verify:

sudo modprobe ryzen_smu
lsmod | grep ryzen_smu

If the MOK Manager screen never appeared, check your BIOS/UEFI for something like "Secure Boot Key Management" or "MOK Management".

2.4 Verify ryzen_smu is working

ls /sys/kernel/ryzen_smu_drv/

Should show files like drv_version, smn, pm_table, etc. If the directory is there and not empty, it's working.

Check version:

cat /sys/kernel/ryzen_smu_drv/drv_version

Needs to be 0.1.7 or newer.

3. 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.

What it does:

  • Installs wget, unzip and curl via your package manager (apt, dnf, yum, pacman, zypper), plus Python 3.10+ if missing
  • 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
  • Chowns /opt/zentune to your user so the TUI can write config without root
  • On update: replaces app files, restarts daemon, keeps your config.ini and custom.json

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

Unsupported package manager (Void, Gentoo, NixOS, etc.): the installer checks whether wget/curl and unzip are already present. If they are, it skips the package step. If anything is missing it lists what's needed and exits.

No systemd (OpenRC, runit, s6, etc.): the installer completes normally and prints the daemon start command at the end:

sudo /opt/zentune/venv/bin/python3 /opt/zentune/src/Assets/daemon/daemon.py

Run that before launching the app. For service file examples, see Manual installation.

4. First run

zentune

The setup wizard runs automatically the first time. It's a three-step dialog:

Step 1: Welcome. An intro screen. Press Begin setup to continue.

Step 2: Background daemon. Press Install / enable daemon. You'll be asked for your password (the daemon needs root). The wizard creates and starts zentune.service, then shows Daemon: running. Continue unlocks once it's up. Without systemd, this step prints the manual start command; run it in another terminal (see Manual installation), and it'll be detected.

Step 3: Detect hardware. Runs automatically when you reach this step. Shows your CPU family, architecture, type and preset profile, e.g. Family HawkPoint, Type Amd_Apu. If it shows Unknown, see Linux Troubleshooting and press Detect again. Press Finish to get to the main screen.

Once setup finishes, the app opens on the Home tab. Press 1 (or open the Premade tab) to apply your first preset.

Getting around the app

The interface is a set of tabs. Switch between them with the number keys or by clicking:

Key Tab What it's for
h Home Live CPU graphs and a jump-off point to every other tab
1 Premade Apply Eco / Balance / Performance / Extreme
2 Custom Build and apply your own preset (Custom Presets)
3 Adaptive Live tuning from temperature and load (Adaptive Mode)
4 Auto AC/battery and resume preset switching
5 Info CPU, board and cache details
6 Status Daemon state and the last SMU apply output
7 Settings Daemon service, reapply, hardware re-detect, reset
? - About / check for updates
q - Quit

5. Updating

The app checks GitHub on launch (when Software update is on) and offers to update when a newer version is out. It backs up config.ini and custom.json, replaces the app files, restores settings, restarts the daemon and relaunches.

Force an update anytime from About (?) -> Check updates: Update now for the latest stable, Switch to beta for the rolling beta build.

Re-running the install script also works: pulls the latest release, reinstalls deps into the venv, restarts the daemon if systemd is active, keeps your config and presets.

If you're still on UXTU4Linux v1.1.0, "Check updates" walks you through a one-time automatic migration to ZenTune instead, your settings and presets carry over, no manual steps required.

6. Uninstalling

The easy way

Run the install script with --uninstall. It removes the systemd service, launcher, /opt/zentune, and any leftover sockets and lock files.

If you still have the script locally:

bash install.sh --uninstall

Or fetch and run it in one line:

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

Asks for confirmation, then removes:

Item Path
systemd service (if present) /etc/systemd/system/zentune.service
Launcher /usr/local/bin/zentune
App, venv and config /opt/zentune
Runtime socket / lock /run/zentune.sock, /run/zentune_daemon.lock
TUI lock /tmp/zentune_tui.lock

To skip the confirmation prompt (for scripts), set ZENTUNE_ASSUME_YES=1:

ZENTUNE_ASSUME_YES=1 bash install.sh --uninstall

From inside the app

Settings (7) -> Daemon service -> Uninstall removes the systemd service only: stops, disables, deletes the unit. App files and venv stay. Use the script above to remove everything.

Doing it by hand

If you installed manually or want to remove things one at a time:

# If you have systemd
sudo systemctl disable --now zentune.service
sudo rm -f /etc/systemd/system/zentune.service
sudo systemctl daemon-reload

# Everything else
sudo rm -f /usr/local/bin/zentune
sudo rm -rf /opt/zentune
sudo rm -f /run/zentune.sock /run/zentune_daemon.lock
rm -f /tmp/zentune_tui.lock

The ryzen_smu kernel module is installed separately and isn't touched by any of this. To remove it:

cd ryzen_smu
sudo make dkms-uninstall

7. Manual installation

Don't want to curl a script straight into bash? Clone the repo and run the installer from your own checkout instead of downloading a release:

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

This is the same installer as the one-line command in step 3, just pointed at your local clone instead of the latest GitHub release. It sets up the venv, copies the app to /opt/zentune, creates the zentune launcher, and (on systemd systems) installs the service, same as a normal install. Everything in steps 4 onward applies the same way.

For OpenRC, runit, s6 or another non-systemd init system, install.sh skips the service step and the setup wizard offers a manual-start command instead; wrap that command in a service definition for your init system to have the daemon start automatically.

Report an issue · Releases

Home

Getting started

Using the app

Internals

Clone this wiki locally