CoolerControl

Main Navigation:

Features - Getting Started - Hardware Support - Issues - Contributing - Acknowledgements - License - Related Projects

The Wiki Pages

What Is This?

CoolerControl is a feature-rich cooling device control application for Linux. It has a system daemon for background device management, as well as a GUI to expertly customize your settings.

What Features Does It Have?

• A highly configurable GUI with system overview
• A control daemon that runs in the background
• Auto detection of hwmon/sysfs and liquidctl devices including some laptops
• Enhanced liquidctl device support (AIOs, USB Fan hubs, LCD screens, RGB lighting, etc)
• Fan control support for most NVidia and AMD GPUs
• Fully customizable speed Profiles like Fixed, Graph(Curve), and Mix that can be applied to multiple fans
• Functions to control how a Profile is applied with hysteresis, threshold, directional, and response time control
• System-wide cooling Modes to adjust all your devices at once
• Create your own Custom Sensors based on a File or on a combination of temperature sensors
• Combine Profiles from multiple devices for complete cooling coverage
• Re-applies settings after waking from sleep
• External monitoring and GUI support
• Comprehensive REST API for extensions

How do I Get Started?

CoolerControl is made up of several sub-packages:

1. coolercontrold - the main daemon and systemd service that handles controlling your hardware.
2. coolercontrol-liqctld - a systemd service layer over liquidctl.
3. coolercontrol - the standalone GUI desktop application.

#1 and #2 are required. #3 is technically optional, as the GUI can also be accessed from the daemon using a browser.

You'll want to first install the application packages following the installation steps below and then you can access the GUI in one of two ways:

1. Open the standalone GUI application coolercontrol from your desktop.
2. Open a browser and go to http://localhost:11987

The following are some recommended steps to become familiar with the UI and how to create your customized settings:

1. Explore the UI Menu on the left. Notice what clicking on each menu item does and the little options menus available for each one.
2. Click on "Profiles & Functions". Notice the small info icons next to the headings. Hover over them for more information. Lots of things in the UI you can hover over for more details.
3. Open the Settings menu by clicking on the settings icon in the upper right hand corner. Notice how you can hover over most settings for an explanation of what each one does.
4. Start creating Profiles and Functions, exploring their settings, and apply them to your desired fans or pumps.
5. Create Modes to be able to swap out your profiles when desired.

*Note: You can modify and control the daemon using its config file, but that is not officially supported.

How do I Install It?

• AppImage
• AUR
• Ubuntu/Debian Based
• Fedora
• OpenSuse Tumbleweed
• Nix
• Gentoo
• From Source

Why is my hardware not showing/working?

CoolerControl depends on Hwmon kernel drivers and liquidctl to access and control supported hardware. Note that your hardware is not guaranteed to be supported, as this depends on open-source drivers and contributors. The following are the steps you should take to maximize hardware coverage:

• To have all available kernel modules installed for your hardware it's recommended to install lm-sensors and to run sudo sensors-detect. For more details see the Arch Wiki and the HWMon Support section. Additionally, you can check out the official lm-sensors repository for tips on manually loading unofficial kernel modules for hardware that isn't supported out-of-the-box.
• For newer motherboards and cards it's best to install the latest available kernel for your distribution which includes the latest Hwmon drivers and kernel modules.
• Check the liquidctl hardware support list for the state of support for USB devices like fan hubs and AIOs.
• NVidia GPUs - Fan control is currently tested working for most cards and setups. CoolerControl will try to communicate directly with the NVML if possible, and use the CLI tools: nvidia-settings and nvidia-smi as an alternative.
• AMD RDNA 3 GPUs - There have been significant changes in how fan control works with newer cards. In particular the 7000 series and above will use fan speeds set by CoolerControl if you enable the fan control feature by setting the kernel boot option: amdgpu.ppfeaturemask=0xffffffff. But note that the fan will only kick in once a builtin (non-configurable) temperature threshold has been reached. It has been reported that that they will generally start at 60C and stop at 50C (Junction Temp).
• Laptops - ThinkPads, some ASUS, and some HP Laptops are known to have supported drivers, but not all. If your laptop has a hwmon kernel driver, then CoolerControl will use it. Otherwise, fan control for your laptop is most likely not supported.
• CoolerControl will detect supported devices and available capabilities automatically. The GUI will also prompt you for additional steps if necessary. There are some situations where the kernel drivers are not yet mature enough to offer control functionality, in which cases an error is returned when attempting to apply changes.

AppImage

CoolerControlD Daemon

---

CoolerControl Desktop App (Optional)

There are two AppImages:
CoolerControlD which runs as a daemon in the background and needs sudo access.
CoolerControl which is the standalone GUI application. (Optional)

To download them you can use either of the above links or goto the Releases page to download a specific version.

The AppImages are helpful if you want to try things out without installing anything. It is generally recommended to install the systems packages, as it is then installed as a systemd service which starts at boot and version updates are handled automatically.

The AppImages contain most of the needed dependencies*. Just make it executable and run it:

chmod +x CoolerControlD-x86_64.AppImage
chmod +x CoolerControl-x86_64.AppImage
# start daemon in the background
sudo ./CoolerControlD-x86_64.AppImage &
./CoolerControl-x86_64.AppImage

* ⚠️ on some systems you'll have to install libfuse2 or fuse for appimages to work.

Click for more info about AppImages

AppImage Website

For improved desktop integration:

• AppImageLauncher
• appimaged

AUR

There are official binary and source packages in the AUR.

Use your installed AUR Helper, i.e.:

# binary package
yay -S coolercontrol-bin

# source package
yay -S coolercontrol

Then enable and start the systemd service:

sudo systemctl enable --now coolercontrold

Upgrading from v1.4.0

If you already have coolercontrol<=1.4.0 installed from the AUR, you will need to remove it to update to a newer version.

This is required even if you want to keep using the source package.

# Stop and disable the systemd service
sudo systemctl disable --now coolercontrold

# Remove coolercontrol and all of its dependencies (your settings will remain)
sudo pacman -Rns coolercontrol

# Install your preferred package
yay -S coolercontrol-bin

# Reenable and start the systemd service
sudo systemctl enable --now coolercontrold

Packages

Package repositories for some distros is graciously provided by Cloudsmith - a fully hosted, cloud-native, universal package management solution.

Debian

Debain packages are supported for the following distros:

• >= Debian Bookworm
• >= Ubuntu 22.04 (Jammy)
• Most other distributions based on the above.
• Kali Linux is currently not supported due to a limitation with their official package repository. Kali users will need to either use the AppImage or install from source.

You can quickly setup the Cloudsmith repository automatically (recommended):
*Other Cloudsmith Options

Make sure curl is installed:

sudo apt install curl apt-transport-https

curl -1sLf \
  'https://dl.cloudsmith.io/public/coolercontrol/coolercontrol/setup.deb.sh' \
  | sudo -E bash

sudo apt update
sudo apt install coolercontrol

sudo systemctl enable --now coolercontrold

Ubuntu 22.04 LTS (Optional)

The Ubuntu package liquidctl is outdated. Therefore, some devices might not show, such as the NZXT Smart Device V2. To fix this, you can force upgrade the package:

⚠️ Before proceeding, make sure to run the commands outlined above.

sudo systemctl stop coolercontrold
sudo pip install liquidctl --upgrade
sudo systemctl start coolercontrold

You might need to restart your computer for the changes to take effect

Fedora

There is a Copr repository available for Fedora based distributions:

# make sure you have the necessary plugin:
sudo dnf install dnf-plugins-core
sudo dnf copr enable codifryed/CoolerControl
sudo dnf install coolercontrol
sudo systemctl enable --now coolercontrold

OpenSuse Tumbleweed

Packaging is done on the Open Build Service for openSuse Tumbleweed and there are two easy ways to install the packages:

1. You can use the 1-Click-Install method.
2. Or install from the command line:

# make sure opi is installed if it's not already:
sudo zypper install opi
opi coolercontrol

Then enable and start the systemd service:

sudo systemctl enable --now coolercontrold

Nix

The coolercontrol package is currently a part of the nixpkgs-unstable and nixos-unstable channels.

For NixOS there are is a configuration option available, which should install the application and enable the services:

programs.coolercontrol.enable = true;

And an option for NVidia graphic card owners that should default to on if you have the nvidia driver in services.xserver.videoDrivers:

programs.coolercontrol.nvidiaSupport = true;

If installing using the Nix package manager on a non-NixOS distro, you'll need to do some things manually. For example:

# Make sure your channel is up to date
nix-channel --update
nix-env -iA nixpkgs.coolercontrol
sudo systemctl enable --now ~/.nix-profile/lib/systemd/system/coolercontrold.service ~/.nix-profile/lib/systemd/system/coolercontrol-liqctld.service

⚠️ On non-NixOS, this will enable the services for the currently installed version. You need to disable the services and re-enable them after each update. systemctl reenable will not work.

Gentoo

Gentoo users can use these unofficial portage overlays:

• https://gpo.zugaina.org/sys-apps/coolercontrol-liqctld
• https://gpo.zugaina.org/sys-apps/coolercontrold
• https://gpo.zugaina.org/sys-apps/coolercontrol

Note: There is an issue currently with the WebUI. See #341

Cloudsmith Options

For other options, such as if you need to force a specific distribution, release/version, or you want to do the steps manually, check out the CoolerControl repository on Cloudsmith. When running a distribution that is based on another, but not natively supported by Cloudsmith, you can use the base-distribution repository. For example:

curl -1sLf \
  'https://dl.cloudsmith.io/public/coolercontrol/coolercontrol/setup.rpm.sh' \
  | sudo -E distro=fedora codename=38 bash

Repository Alternative

You can download the package files directly from the Releases Page and install the packages manually.

Source

Requirements

• git
• make
• cargo/rust >= 1.81.0
• python >= 3.8
• nodejs >= 18.0.0
• npm
• libdrm-dev

Note: If you are running Arch Linux, installing from source requires special steps that the official AUR package already does for you.

System Packages

To optionally build the standalone GUI application you'll also need these Tauri development packages.

Setup Source

git clone https://gitlab.com/coolercontrol/coolercontrol.git
git checkout main
git pull

Build and Install Everything

cd coolercontrol
make install-source -j3
# and watch it go.

That should install all the needed files onto your system.

Then start the daemons:

sudo systemctl daemon-reload
sudo systemctl enable --now coolercontrold

You should then be able to start the GUI like normal.

---

What Do I Do If I Have A Problem Or Question?

If you are experiencing an issue or have a feature request, please open up an issue in GitLab and use one of the provided templates. When submitting a bug daemon logs are invaluable to determining the cause. If you have a general question, please join the discord channel where community members can also help.

How Can I Contribute?

❤️ CoolerControl is in need of help with the following areas:

• Packaging
• Website
• Spreading the word

If you have an idea or want to submit some changes, it's usually best to either submit an Issue ticket first or get on Discord to discuss it. For general information please read the contributing guidelines.

Acknowledgements

• Major thanks is owed to the python API of liquidctl
• Thanks to all the many contributors of HWMon
• A big inspiration is GKraken written by Roberto Leinardi.

License

This program is licensed under GPLv3+

Related Projects

• liquidctl
  Cross-platform tool and drivers for liquid coolers and other devices.

• fan2go
  A daemon to control the fans of your computer.

• thinkfan
  A simple, lightweight fan control program. (ThinkPads)

• OpenRGB
  Graphical interface to control many different types of RGB devices.

• FanControl
  A focused and highly customizable fan controlling software for Windows.