liquidctl – liquid cooler control
Cross-platform tool and drivers for liquid coolers and other devices
# liquidctl list Device 0, NZXT Kraken X (X42, X52, X62 or X72) # liquidctl initialize # liquidctl status Device 0, NZXT Kraken X (X42, X52, X62 or X72) Liquid temperature 29.4 °C Fan speed 639 rpm Pump speed 1910 rpm Firmware version 4.0.2 # liquidctl set pump speed 90 # liquidctl set fan speed 20 30 30 50 34 80 40 90 50 100 # liquidctl set ring color fading 350017 ff2608 # liquidctl set logo color spectrum-wave
Table of contents
- Supported devices
- Getting liquidctl
- The command-line interface
- Automation and running at boot
- Related projects
|Device and link to documentation||Monitoring||Cooling||Lighting||Notes|
|Corsair H80i, H100i or H110i GTX||✓'||✓'||✓'|
|Corsair H80i v2, H100i v2 or H115i||✓'||✓'||✓'|
|EVGA CLC 120 (CL12), 240 or 280||✓||✓||✓|
|NZXT Grid+ V3||✓'||✓'|
|NZXT Kraken M22||✓|
|NZXT Kraken X40 or X60||✓'||✓'||✓'||requires
|NZXT Kraken X31, X41 or X61||✓'||✓'||✓'||requires
|NZXT Kraken X42, X52, X62 or X72||✓||✓||✓|
|NZXT Smart Device||✓||✓||✓|
␣ Not available at the hardware level
Depending on the platform, PyUSB might require the installation of a suitable backend (e.g. libusb) or special kernel drivers. HIDAPI's dependencies can also vary a lot. Known platform details and quirks are documented bellow, after the common installation instructions.
Installing liquictl the Pythonic way
The easiest way to get liquidctl is to grab a release from PyPI with pip. For currently under development features, pip can also be used to install the latest snapshot of the official repository.
# pip install liquidctl # pip install liquidctl==<version> # pip install git+https://github.com/jonasmalacofilho/liquidctl
Contributors to the project's code or documentation will want to manually clone the repository and install liquidctl in editable mode.
$ git clone https://github.com/jonasmalacofilho/liquidctl $ cd liquidctl # pip install --editable .
Of course, a virtual environment can always be used instead of installing the package globally.
Pre-built packages and executables
Packages for Linux distributions:
Pre-built binaries for Windows:
- Releases: check the Releases tab
- Development builds: select from the last builds on AppVeyor and check the artifacts tab
Additional requirements on Linux
Installing HIDAPI on Linux requires locally building some C extensions (automatically). Both libusb-1.0 and libudev are needed for this, together with their corresponding development files. You may also need development files for Python.
|Linux dependency||Arch Linux||Fedora||Ubuntu|
|build tools||base-devel||"Development Tools"||build-essential|
Additional requirements on Windows
Products which are not Human Interface Devices (HIDs) – i.e. that do not use the generic Microsoft HID Driver – require installing a kernel driver compatible with libusb. The recommended way to do this is with Zadig, selecting the WinUSB option.
On Windows libusb v1.0.21 is prefered over later versions, because of a known issue with PyUSB that causes errors when the devices are released.
Pre-build liquidctl executables for Windows already include libusb and HIDAPI, but when installing from PyPI or the sources you will need to manually set up the libusb runtime libraries. Download the package from libusb/releases and extract the appropriate (e.g. MS64)
.lib files to your system or python installation directory (e.g.
Additional requirements on Mac OS
Apple revamped its USB stack in 10.11, with a heavy reliance on ACPI. Their kernel also communicates with Human Interface Devices (HIDs) in exclusive mode, unlike Windows, which can operate in shared mode, and Linux, which can seamlessly switch between drivers.
Because of this, liquidctl will default to HIDAPI when dealing with HIDs on Mac OS, as it does not require unloading the kernel HID driver. Pip or setuptools should be able to build it automatically, when installing liquidctl.
Libusb is still required though, as it might be used to probe and interact with non HID coolers and other products. It can easily be installed through homebrew:
brew install libusb.
Introducing the command-line interface
The complete list of commands and options can be seen with
liquidctl --help, but a good place to start is to ask liquidctl to list all recognized devices.
# liquidctl list
In case more than one supported device is found,
--usb-port can be used to select a particular product (see
The numbers shown by
list can also be used for device selection with
--device <no>. However, these numbers are not guaranteed to remain stable and will vary with hardware changes, liquidctl updates or simply normal enumeration order variance.
Devices will usually need to be initialized before they can be used, though each device has its own requirements and limitations. This and other information specific to a particular device will appear on the documentation linked in the supported devices section.
# liquidctl initialize
Most devices provide some status information, like fan speeds and liquid temperatures. This can be queried for all devices or using the filtering methods mentioned before.
# liquidctl [options] status
Fan and pump speeds can be set to fixed values or, if the device supports them, custom profiles.
# liquidctl [options] set <channel> speed (<temperature> <percentage>) ... # liquidctl [options] set <channel> speed <percentage>
Lighting is controlled in a similar fashion and, again, the specific documentation lists the available channels, modes and other details. The animation speed can be controlled with the
# liquidctl [options] set <channel> color <mode> [<color>] ...
--verbose option will print some extra information, like automatically made adjustments to the user provided settings. And if there is a problem, the
--debug flag will print as much information as possible to help identify its cause; be sure to include it when opening a new issue.
Automation and running at boot
In most cases you will want to automatically apply your settings when the system boots. Generally a simple script or a basic service is enough for, and some specifics about this are given in the following sections.
If you need more control for some really ambitious automation, you can also write a Python program that calls the driver APIs directly.
Set up Linux using systemd
On systems running Linux and Systemd, a service unit can be used to configure liquidctl devices. A simple example is provided bellow, you can edit it to match your preferences and save the result to
[Unit] Description=AIO startup service [Service] Type=oneshot ExecStart=liquidctl set pump speed 90 ExecStart=liquidctl set fan speed 20 30 30 50 34 80 40 90 50 100 ExecStart=liquidctl set ring color fading 350017 ff2608 ExecStart=liquidctl set logo color spectrum-wave [Install] WantedBy=default.target
The unit can be started manually or set to automatically run during boot using standard Systemd tools:
# systemctl start liquidcfg # systemctl enable liquidcfg
A slightly more complex example can be seen at jonasmalacofilho/dotfiles, that handles multiple devices and uses the LEDs to convey progress or eventual errors.
Set up Windows using Task Scheduler
The configuration of devices can be automated by writing a batch file and setting up a new scheduled task for (every) log on. The batch file can be really simple and just list the various invocations of liquidctl you would otherwise do by hand.
liquidctl set pump speed 90 liquidctl set fan speed 20 30 30 50 34 80 40 90 50 100 liquidctl set ring color fading 350017 ff2608 liquidctl set logo color spectrum-wave
Make sure that Python and executables from its packages are available in the context where the batch file will run: in short,
python --version and
liquidctl --version should work within a normal Command Prompt window.
If necessary, try installing Python with the option to set the PATH variable enabled, or manually add the necessary folders to the PATH. Alternatively, if you're using Anaconda, try adding the following line to the beginning of the file:
A slightly more complex example can be seen in issue #14 ("Can I autostart liquidctl on Windows?"), that uses the LEDs to convey progress or eventual errors.
Chris' guide on Replacing NZXT’s CAM software on Windows for Kraken goes into a lot more detail and is a good read.
Set up Mac OS using launchd
You can use a shell script and launchd to automatically configure your devices upon logging in.
Create a script in
/usr/local/bin/liquidcfg.sh and make it executable; it should contain the calls to liquidctl necessary to initialize and configure your devices.
#!/bin/bash -xe liquidctl set pump speed 90 liquidctl set fan speed 20 30 30 50 34 80 40 90 50 100 liquidctl set ring color fading 350017 ff2608 liquidctl set logo color spectrum-wave
Afterwards, create a new global daemon in
/Library/LaunchDaemons/local.liquidcfg.plist that executes the previous script.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>ProgramArguments</key> <array> <string>/usr/local/bin/liquidcfg.sh</string> </array> <key>Label</key> <string>local.liquidcfg</string> <key>RunAtLoad</key> <true/> <key>KeepAlive</key> <false/> <key>EnvironmentVariables</key> <dict> <key>PATH</key> <string>/Library/Frameworks/Python.framework/Versions/?.?/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string> </dict> </dict> </plist>
It is important to adjust the location of Python 3 framework in the PATH environment variable above. launchd agents use the system profile and thus will by default only find the Apple-provided Python 2.7 and its packages.
You can enable and disable the agent with
launchctl load|unload ~/Library/LaunchAgents/local.liquidcfg.plist. Errors can be found in
system.log using Console; search for
A real world example can be seen in icedterminal/ga-z270x-ug.
Copyright (C) 2018–2019 Jonas Malaco
Copyright (C) 2018–2019 each contribution's author
Incorporates or uses as reference work by leaty, KsenijaS, Alexander Tong, Jens Neumaier, Kristóf Jakab, Sean Nelson and Chris Griffith, under the terms of the GNU General Public License.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.
Ongoing work on Linux kernel drivers that implement standard hwmon sysfs interfaces for the devices supported by liquidctl and allow the use of standard monitoring tools (e.g. lm-sensors).
Linux kernel USB drivers for second and third generation NZXT Kraken X coolers.
Command-line tool to control Corsair all-in-one liquid coolers and other devices.
A related cross-plataform interface for controlling third generation NZXT Kraken X coolers.
A special thanks to all krakenx contributors; this project would not exist were not for it.