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

1. Supported devices
2. Getting liquidctl
   1. The Pythonic way
   2. Pre-built packages and executables
   3. Additional requirements on Linux
   4. Additional requirements on Windows
   5. Additional requirements on Mac OS
3. The command-line interface
4. Automation and running at boot
   1. Set up Linux using systemd
   2. Set up Windows using Task Scheduler
   3. Set up Mac OS using launchd
5. License
6. Related projects

¹ Experimental.
² Use with --legacy-690lc flag.

liquidctl requires Python 3. Along with a couple of more general Python libraries, PyUSB and (Cython) HIDAPI are used to communicate with devices.

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.

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.

Packages for Linux distributions:

• ArchLinux: python-liquidctl^AUR, python-liquidctl-git^AUR
• Fedora: liquidctl, python3-liquidctl

Pre-built binaries for Windows:

• Releases: check the assets in the Releases tab
• Development builds: select from the last builds on AppVeyor and check the artifacts tab

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.

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) .dll and .lib files to your system or python installation directory (e.g. C:\Windows\System32 or C:\Python36).

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.

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, --vendor, --product, --release, --serial, --bus, --address and --usb-port can be used to select a particular product (see liquidctl --help).

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 --speed flag.

# liquidctl [options] set <channel> color <mode> [<color>] ...

Finally, the --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, possibly in combination with setting PYSUB_DEBUG=debug, will make liquidctl output as much information as possible to help identify its cause; be sure to use these features when opening a new issue.

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.

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 /etc/system.d/system/liquidcfg.service.

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

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:

call %homepath%\Anaconda3\Scripts\activate.bat

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.

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 liquidcfg or liquidctl.

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.