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
3. The command-line interface
4. Automation and running at boot
5. License
6. Related projects

✓   Implemented
✓'  Experimental
✗   Missing/locked
_   Not available at the hardware level

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
• Fedora (28, 29, Rawhide): liquidctl, python3-liquidctl

Pre-built binaries for Windows:

• Releases: check the Releases tab
• Nightly builds: check AppVeyor's artifacts tab

liquidctl uses PyUSB to communicate with USB devices, and thus a suitable backend for it must be available at runtime.

Pre-built packages and executables should take of these dependencies automatically. And if you use other user-space programs that interact with USB devices, it is possible that you already installed compatible libraries.

In all other cases we recommend you install libusb-1.0. On Linux, it is usually available in a libusb-1.0 or similar pacakge.

On Windows, version libusb v1.0.21 is recommended over the latest, because of a known issue with PyUSB that causes errors when releasing the device. Download the package from libusb/releases and extract appropriate (e.g. MS64) .dll and .lib files to your system or python installation directory (e.g. C:\Windows\System32 or C:\Python36).

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, they can be selected with the --device <no> option, according to the output of list. They can also be filtered by --vendor id, --product id, --usb-port, or even --serial number.

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 will print as much information as possible to help identify its cause; be sure to include it 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.

Copyright (C) 2018–2019 Jonas Malaco
Copyright (C) 2018–2019 each contribution's author

Incorporates work by leaty, KsenijaS, Alexander Tong and Jens Neumaier, 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/.

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.

Linux kernel-space driver for second and third generation NZXT Kraken X coolers.

Command-line tool to control Corsair all-in-one liquid coolers and other devices.