auto-cpufreq

Automatic CPU speed & power optimizer for Linux. Actively monitors laptop battery state, CPU usage, CPU temperature, and system load, ultimately allowing you to improve battery life without making any compromises.

For tl;dr folks:

Youtube: auto-cpufreq v2.0 release & demo of all available features and options
Blog post: auto-cpufreq v2.0

Youtube: auto-cpufreq - tool demo
Blog post: auto-cpufreq – Automatic CPU speed & power optimizer for Linux

If you're having a problem with auto-cpufreq, before (submitting an issue), it is strongly recommended to use the auto-cpufreq-genAI-chatbot to get an immediate answer to your question.

Example of auto-cpufreq GUI (v3.2.0)

Example of auto-cpufreq --stats CLI output (v3.2.0)

Example of auto-cpufreq v3.2.0 CLI output

Looking for developers and co-maintainers

If you would like to discuss anything regarding auto-cpufreq or its development, please join the auto-cpufreq Discord server!
auto-cpufreq is looking for co-maintainers & open source developers to help shape the future of the project!

Index

Why do I need auto-cpufreq?
- Supported architectures and devices
Features
Installing auto-cpufreq
Post-installation
Configuring auto-cpufreq
How to run auto-cpufreq
auto-cpufreq modes and options
Intel HWP Dynamic Boost
Platform Profiles
Battery charging thresholds
Troubleshooting
- AUR
Discussion
Donate
- Financial donation
- Code contribution

Why do I need auto-cpufreq?

One of the problems with Linux today on laptops is that the CPU will run in an unoptimized manner which will negatively impact battery life. For example, the CPU may run using the "performance" governor with turbo boost enabled regardless of whether it's plugged into a power outlet or not.

These issues can be mitigated by using tools like indicator-cpufreq or cpufreq, but those still require manual action from your side which can be daunting and cumbersome.

Tools like TLP (which I used for numerous years) can help extend battery life, but may also create their own set of problems, such as losing turbo boost.

Given all of the above, I needed a simple tool that would automatically make CPU frequency-related changes and save battery life, but let the Linux kernel do most of the heavy lifting. That's how auto-cpufreq was born.

Please note: auto-cpufreq aims to replace TLP in terms of functionality, so after you install auto-cpufreq it's recommended to remove TLP. Using both for the same functionality (i.e., to set CPU frequencies) will lead to unwanted results like overheating. Hence, only use both tools in tandem if you know what you're doing.

One tool/daemon that does not conflict with auto-cpufreq in any way, and is even recommended to have running alongside, is thermald.

Supported architectures and devices

Only devices with an Intel, AMD, or ARM CPU are supported. This tool was developed to improve performance and battery life on laptops, but running it on desktops/servers (to lower power consumption) should also be possible.

Features

Monitoring
- Basic system information
- CPU frequency (system total & per core)
- CPU usage (system total & per core)
- CPU temperature (total average & per core)
- Battery state
- System load
CPU frequency scaling, governor, and turbo boost management based on
- Battery state
- CPU usage (total & per core)
- CPU temperature in combination with CPU utilization/load (to prevent overheating)
- System load
Automatic CPU & power optimization (temporary and persistent)
Platform Profile monitoring and configuration, when exposed by the Linux platform driver
- Current platform profile
- Available profiles
- Platform Profile provider(s)
- Separate charger and battery configuration
Settings battery charging thresholds (limited support)

Installing auto-cpufreq

auto-cpufreq-installer

The source installer automatically handles several major Linux distribution families, including Debian/Ubuntu (and derivatives such as Linux Mint), Fedora/RHEL, Arch-based distributions, openSUSE, Void Linux, and Solus. Other recognized derivatives can use the installation path of their declared base distribution.

Source installation requires a distribution-provided Python 3.9 or newer. Enterprise Linux 8 uses its Python 3.9 stream; newer Enterprise Linux releases use the distribution's default Python 3.

The installer automatically installs system dependencies and creates each source installation in a dedicated virtual environment under /opt/auto-cpufreq/releases. It verifies a new installation before atomically selecting it through /opt/auto-cpufreq/current; an incomplete installation does not replace the working one.

NixOS uses the native Nix integration described below instead of the source installer.

For a stable source installation, download the .zip or .tar.gz source archive for the desired version from GitHub Releases, extract it, enter the extracted directory, and run:

sudo bash ./auto-cpufreq-installer

Release archives published before this archive metadata support was added are not changed retroactively and may still require a Git checkout.

For the current development version, clone the Git repository instead:

git clone https://github.com/AdnanHodzic/auto-cpufreq.git
cd auto-cpufreq && sudo ./auto-cpufreq-installer

When replacing an existing source installation, remove its auto-cpufreq daemon first if the installer asks you to do so. Earlier versioned generations are retained until the source installation is removed.

Debian repositories (.deb package)

auto-cpufreq has been added to official Debian repositories, and will soon make its way to other derivatives like Ubuntu, Mint and et cetera.

sudo apt install auto-cpufreq

The Debian package is currently being maintained by emfox.

Snap Store

Please note: while all auto-cpufreq >= v2.0 CLI functionality will work as intended, the GUI won't be available on Snap package installs due to Snap package confinement limitations. Hence, please consider installing auto-cpufreq using auto-cpufreq-installer.

auto-cpufreq is available on the Snap Store or via CLI:

sudo snap install auto-cpufreq

Please note:

Make sure snapd is installed and snap version is >= 2.44 for auto-cpufreq to fully work due to recent snapd changes.
Fedora users will encounter the following error due to cgroups v2 being in development. This problem can be resolved by either running sudo snap run auto-cpufreq after the snap installation or by using the auto-cpufreq-installer which doesn't have this issue.

AUR package (Arch based distributions)

The AUR Release Package is currently being maintained by MusicalArtist12, liljaylj, and parmjotsinghrobot.

Notices

The Git Package is seperately maintained and was last updated on version 1.9.6.
The build process links to /usr/share/ instead of /usr/local/share/
The daemon installer provided does not work, instead start the daemon with

# systemctl enable --now auto-cpufreq

The GNOME Power Profiles daemon is automatically disabled by auto-cpufreq-installer due to it's conflict with auto-cpufreq.service. However, this doesn't happen with AUR installs, which can lead to problems (e.g., #463) if not masked manually.
- Open a terminal and run sudo systemctl mask power-profiles-daemon.service (then enable and start the auto-cpufreq.service if you haven't already).
The TuneD daemon(enabled by default with Fedora 41) is automatically disabled by auto-cpufreq-installer due to it's conflict with auto-cpufreq.service.

Gentoo Linux (GURU Repository)

New versions of auto-cpufreq were recently added to GURU, Gentoo's official community-maintained ebuild repository. The ebuild is maintaned by S41G0N and other GURU contributors, who can respond in case of issues.

In order to build auto-cpufreq, it is necessary to add & sync GURU repository first. Adding ~amd64 keyword is also needed to unmask the package.

# echo "sys-power/auto-cpufreq ~amd64" >> /etc/portage/package.accept_keywords
# eselect repository enable guru
# emaint sync -r guru
# emerge --ask auto-cpufreq

Notices

The build process links to /usr/share/ instead of /usr/local/share/
The build works on both systemd/OpenRC systems (both systemd and OpenRC will have a service called auto-cpufreq which can be started automatically)
The daemon installer provided does work, but it is RECOMMENDED to install the daemon with:

# systemctl enable --now auto-cpufreq 
# rc-update add auto-cpufreq default && rc-service auto-cpufreq start

NixOS

Flakes

This repo contains a flake that exposes a NixOS Module that manages and offers options for auto-cpufreq. To use it, add the flake as an input to your flake.nix file and enable the module:

# flake.nix

{

    inputs = {
        # ---Snip---
        auto-cpufreq = {
            url = "github:AdnanHodzic/auto-cpufreq";
            inputs.nixpkgs.follows = "nixpkgs";
        };
        # ---Snip---
    }

    outputs = {nixpkgs, auto-cpufreq, ...} @ inputs: {
        nixosConfigurations.HOSTNAME = nixpkgs.lib.nixosSystem {
            specialArgs = { inherit inputs; };
            modules = [
                ./configuration.nix
                auto-cpufreq.nixosModules.default
            ];
        };
    } 
}

Then you can enable the program in your configuration.nix file:

# configuration.nix

{inputs, pkgs, ...}: {
    # ---Snip---
    programs.auto-cpufreq.enable = true;
    # optionally, you can configure your auto-cpufreq settings, if you have any
    programs.auto-cpufreq.settings = {
    charger = {
      governor = "performance";
      turbo = "auto";
    };

    battery = {
      governor = "powersave";
      turbo = "auto";
    };
  };
    # ---Snip---
}

Nixpkgs

There is a nixpkg available. Its version depends on the selected nixpkgs revision, while the flake input is pinned by flake.lock. You can install it in your configuration.nix and enable the system service:

# configuration.nix

# ---Snip---
environment.systemPackages = with pkgs; [
    auto-cpufreq
];

services.auto-cpufreq.enable = true;
# ---Snip---

Installation (development mode only)

For development setup, the current module ownership map, and the frontend and diagnostic architecture, consult CONTRIBUTING.md.

If you have poetry installed:

git clone https://github.com/AdnanHodzic/auto-cpufreq.git
cd auto-cpufreq
poetry install
poetry run auto-cpufreq --help

To install with GUI support:

poetry install --extras gui
poetry run auto-cpufreq-gtk

Alternatively, we can use an editable pip install for development purposes:

git clone https://github.com/AdnanHodzic/auto-cpufreq.git
cd auto-cpufreq
# set up virtual environment (details removed for brevity)
pip3 install -e .
auto-cpufreq

If the lock file is inconsistent, check that pyproject.toml and poetry.lock match; use poetry update only when you intend to update dependencies.

Post-installation

After installation, auto-cpufreq is available as a binary. Refer to auto-cpufreq modes and options for detailed information on how to run and configure auto-cpufreq.

Configuring auto-cpufreq

auto-cpufreq makes all decisions automatically based on various factors such as CPU usage, temperature, and system load. However, it's possible to perform additional configurations:

1: power_helper.py script (Snap package install only)

When installing auto-cpufreq via auto-cpufreq-installer, if it detects the GNOME Power Profiles service is running, it will automatically disable it. Otherwise, that daemon will cause conflicts and various other performance issues.

However, when auto-cpufreq is installed as a Snap package it's running as part of a container with limited permissions, hence it's highly recommended to disable the GNOME Power Profiles daemon using the power_helper.py script.

Please Note:
The power_helper.py script is located within the auto-cpufreq repo at auto_cpufreq/power_helper.py. In order to access it, first clone the repository:

git clone https://github.com/AdnanHodzic/auto-cpufreq

The helper requires the project's Python dependencies, including psutil and inotify-simple. Install them in an isolated development environment rather than modifying system Python with --break-system-packages. For example, from the cloned repository with Poetry installed:

cd auto-cpufreq
poetry install
sudo "$(poetry env info --path)/bin/python" -m auto_cpufreq.power_helper --gnome_power_disable

For the list of options, use the same interpreter with --help. inotify-simple 2.0.1 is a separate BSD-2-Clause-licensed dependency; the auto-cpufreq project remains GPL-3.0-or-later.

2: `--force` governor override

By default, auto-cpufreq uses balanced mode which works best for many systems and situations.

However, you can override this behaviour by switching to performance or powersave mode manually. The performance mode results in higher default frequencies, but also higher energy use (battery consumption) and should only be used if maximum performance is needed. The powersave mode does the opposite and extends battery life to its maximum.

See --force flag for more info.

3: `--turbo` mode override

By default, auto-cpufreq handles CPU turbo mode automatically, enabling it under load and disabling it otherwise to balance performance and efficiency.

However, you can override this behavior by forcing CPU turbo's mode to always or never. Setting to always keeps turbo mode always enabled, allowing the CPU to reach its maximum frequency at the cost of higher energy use (battery consumption). never, on the other hand, keeps turbo mode always disabled, limiting the CPU's maximum frequency to extend battery life.

See --turbo flag for more info.

4: auto-cpufreq config file

You can configure separate profiles for the battery and power supply. These profiles will let you pick which governor to use, as well as how and when turbo boost is enabled. The possible values for turbo boost behavior are always, auto, and never. The default behavior is auto, which only activates turbo during high load.

By default, auto-cpufreq does not use a config file. If you wish to configure auto-cpufreq statically, we look for a configuration file in the following order:

Commandline argument: --config <FILE> if passed as commandline argument to auto-cpufreq
User-specific configuration: $XDG_CONFIG_HOME/auto-cpufreq/auto-cpufreq.conf
System-wide configuration: /etc/auto-cpufreq.conf

Example config file contents

Configured to run in full performance mode when connected to a power source (charger) and never drop below 2 GHz. When running on battery, all settings will be configured automatically by auto-cpufreq based on all above mentioned criteria.

# settings for when connected to a power source
[charger]
# see available governors by running: cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_governors
# preferred governor
governor = performance

# EPP: see available preferences by running: cat /sys/devices/system/cpu/cpu0/cpufreq/energy_performance_available_preferences
energy_performance_preference = balance_performance

# Intel HWP Dynamic Boost.
# Only available with intel_pstate in active mode and HWP enabled.
# Alters value in: /sys/devices/system/cpu/intel_pstate/hwp_dynamic_boost
# Accepted values: true/false, yes/no, on/off, 1/0.
# hwp_dynamic_boost = true

# EPB (Energy Performance Bias) for the intel_pstate driver
# see conversion info: https://www.kernel.org/doc/html/latest/admin-guide/pm/intel_epb.html
# available EPB options include a numeric value between 0-15
# (where 0 = maximum performance and 15 = maximum power saving),
# or one of the following strings:
# performance (0), balance_performance (4), default (6), balance_power (8), or power (15)
# if the parameter is missing in the config and the hardware supports this setting, the default value will be used
# the default value is `balance_performance` (for charger)
energy_perf_bias = performance

# Platform Profiles
# https://www.kernel.org/doc/html/latest/userspace-api/sysfs-platform_profile.html
# auto-cpufreq prefers the per-handler /sys/class/platform-profile interface
# when available and retains /sys/firmware/acpi/platform_profile for
# compatibility and safe global control.
# Available values depend on the hardware and kernel. Run `auto-cpufreq --stats`
# or `auto-cpufreq --pp` to see the exact accepted names.
platform_profile = performance

# Controls strict enforcement of the platform profile.
# - true: Continuously restores the configured platform profile.
# - false: Applies it on AC/Battery policy changes while allowing manual
#   firmware or hotkey profile changes in between.
enforce_platform_profile = true

# minimum cpu frequency (in kHz)
# example: for 800 MHz = 800000 kHz --> scaling_min_freq = 800000
# see conversion info: https://www.rapidtables.com/convert/frequency/mhz-to-hz.html
# to use this feature, uncomment the following line and set the value accordingly
scaling_min_freq = 2000000

# maximum cpu frequency (in kHz)
# example: for 1GHz = 1000 MHz = 1000000 kHz -> scaling_max_freq = 1000000
# see conversion info: https://www.rapidtables.com/convert/frequency/mhz-to-hz.html
# to use this feature, uncomment the following line and set the value accordingly
# scaling_max_freq = 1000000

# turbo boost setting. possible values: always, auto, never
turbo = always

# settings for when using battery power
[battery]
# see available governors by running: cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_governors
# preferred governor
#governor = powersave

# EPP: see available preferences by running: cat /sys/devices/system/cpu/cpu0/cpufreq/energy_performance_available_preferences
#energy_performance_preference = balance_power

# Intel HWP Dynamic Boost.
# Only available with intel_pstate in active mode and HWP enabled.
# Alters value in: /sys/devices/system/cpu/intel_pstate/hwp_dynamic_boost
# Accepted values: true/false, yes/no, on/off, 1/0.
# hwp_dynamic_boost = false

# EPB (Energy Performance Bias) for the intel_pstate driver
# see conversion info: https://www.kernel.org/doc/html/latest/admin-guide/pm/intel_epb.html
# available EPB options include a numeric value between 0-15
# (where 0 = maximum performance and 15 = maximum power saving),
# or one of the following strings:
# performance (0), balance_performance (4), default (6), balance_power (8), or power (15)
# if the parameter is missing in the config and the hardware supports this setting, the default value will be used
# the default value is `balance_power` (for battery)
#energy_perf_bias = balance_power

# Platform Profiles
# https://www.kernel.org/doc/html/latest/userspace-api/sysfs-platform_profile.html
# auto-cpufreq prefers the per-handler /sys/class/platform-profile interface
# when available and retains /sys/firmware/acpi/platform_profile for
# compatibility and safe global control.
# Available values depend on the hardware and kernel. Run `auto-cpufreq --stats`
# or `auto-cpufreq --pp` to see the exact accepted names.
#platform_profile = low-power

# Controls strict enforcement of the platform profile.
# - true: Continuously restores the configured platform profile.
# - false: Applies it on AC/Battery policy changes while allowing manual
#   firmware or hotkey profile changes in between.
# enforce_platform_profile = true

# minimum cpu frequency (in kHz)
# example: for 800 MHz = 800000 kHz --> scaling_min_freq = 800000
# see conversion info: https://www.rapidtables.com/convert/frequency/mhz-to-hz.html
# to use this feature, uncomment the following line and set the value accordingly
# scaling_min_freq = 800000

# maximum cpu frequency (in kHz)
# see conversion info: https://www.rapidtables.com/convert/frequency/mhz-to-hz.html
# example: for 1GHz = 1000 MHz = 1000000 kHz -> scaling_max_freq = 1000000
# to use this feature, uncomment the following line and set the value accordingly
# scaling_max_freq = 1000000

# turbo boost setting (always, auto, or never)
#turbo = auto

# battery charging threshold
# reference: https://github.com/AdnanHodzic/auto-cpufreq/#battery-charging-thresholds
#enable_thresholds = true
#start_threshold = end_threshold-1
#stop_threshold = 80

How to run auto-cpufreq

auto-cpufreq can be used through the following CLI modes and the GTK interface:

monitor
- Monitor and see suggestions for CPU optimizations
live
- Monitor and automatically make (temporary) CPU optimizations
install / remove
- Install/remove daemon for (permanent) automatic CPU optimizations
GUI
- View live system and power state, manage supported controls, or preview recommendations
update
- Update auto-cpufreq to the latest release
pp
- Show Platform Profile information
stats
- View live stats of CPU optimizations made by daemon
bluetooth_boot_off
- Turn off Bluetooth on boot (only)! Can be turned on any time later on.
bluetooth_boot_on
- Turn on Bluetooth on boot.
force=TEXT
- Force use of either the "powersave" or "performance" governor, or set to "reset" to go back to normal mode
turbo=TEXT
- Force use of CPU turbo mode, if supported, with "never" or "always", or set to "auto" to automatically handle turbo mode
config=TEXT
- Use config file at designated path
debug
- Show debug info (include when submitting bugs)
version
- Show currently installed version
donate
- To support the project
help
- Shows the available CLI options

Running auto-cpufreq --help will list the available CLI options. Read auto-cpufreq modes and options for more details.

auto-cpufreq modes and options

Monitor

sudo auto-cpufreq --monitor

No changes are made to the system. This is solely to demonstrate what auto-cpufreq could do for your system.

This is the terminal Monitor mode. A read-only Monitor Mode is also available from the GUI when the daemon is not running.

Live

sudo auto-cpufreq --live

Necessary changes are temporarily made to the system over time, but this process and its changes are lost at system reboot. This mode is provided to evaluate how the system would behave with auto-cpufreq permanently running on the system.

GUI

The GTK interface can be opened from the auto-cpufreq desktop entry.

When the daemon is running, the GUI provides a live overview of system, CPU, battery and power state, together with controls for supported auto-cpufreq overrides and settings.

The dashboard refresh interval can be changed from the menu between 1, 2 and 5 seconds.

If the daemon is not running, the GUI offers daemon installation or Monitor Mode for read-only system information and recommendations. The Monitor view is not a separate panel in the running-daemon dashboard.

GTK debug logging

Use Enable debug logging in the GTK menu to start recording a diagnostic session. Logging is disabled by default, but the GTK preference is remembered across launches. The Debug log location dialog displays the selected log filename, its directory, and whether the session is active or has already ended. Copy full path copies the absolute path of the log file (not just the filename or folder); Open folder opens its directory through the desktop's registered file manager. The folder icon beside the GTK configuration path opens the configuration file's parent directory.

No diagnostic directory or log file is created until debug logging is first enabled. If the directory does not exist, the location dialog and the Open folder error explain that logging must be enabled first. Once created, the folder remains accessible even when logging is disabled. Each time logging is enabled, the program starts a new session log; opening the folder does not enable logging.

Diagnostic preferences are stored in $XDG_CONFIG_HOME/auto-cpufreq/gtk-debug.json (default ~/.config/auto-cpufreq/gtk-debug.json). Logs are stored under $XDG_STATE_HOME/auto-cpufreq/ (default ~/.local/state/auto-cpufreq/). The files have private permissions, bounded queues, 1 MiB rotation and up to three backups per session. Review logs before sharing: they may include local paths, system information and Python stack traces.

When enabled, logging records errors and slow or stalled refreshes. It summarizes GTK queueing, data collection, delivery and rendering times approximately once a minute. The process-health sampler runs every 5 seconds and summarizes CPU usage (relative to one logical CPU), memory, thread count and open file descriptors approximately once a minute. It does not continuously log per-thread CPU usage or stacks. Sustained process CPU usage above 70% of one logical CPU for three consecutive samples can trigger a report of the hottest thread and its Python stack; an unresponsive GTK main loop may also produce a stack trace.

This optional GTK logging does not alter the daemon's power policy. The CLI's existing --debug mode remains separate from persistent diagnostic logging.

GTK diagnostic sessions now start only when the GTK entrypoint attaches its main loop; merely importing GTK modules will not launch diagnostic workers.

Optional terminal diagnostics

To record an independent diagnostic session for a terminal screen, add --diagnostic-log to --stats, --monitor or --live:

auto-cpufreq --stats --diagnostic-log

The terminal option is off by default and does not share the GTK preference. It uses the same bounded rotating log writer and process-health sampling as GTK. On unprivileged runs, the log is stored under $XDG_STATE_HOME/auto-cpufreq/ (or ~/.local/state/auto-cpufreq/). For terminal modes run with sudo, logs go to the root account's ~/.local/state/auto-cpufreq/ rather than the invoking user's home; access requires appropriate permissions. Review log contents before sharing. The option is not valid for install, remove, daemon or other noninteractive operations. It does not enable logging for the built-in --debug command.

--stats observes the running daemon without requesting power-policy changes. Unlike --stats, the existing --monitor and --live modes have service and privilege preconditions; do not use them as casual diagnostics of a production system.

Collecting a complete troubleshooting report

For a snapshot of the machine and a short record of refresh timing, collect both sources close together, as two separate commands:

Run auto-cpufreq --stats --diagnostic-log and observe the Stats screen. Press Q to close it, then keep the stats-*.log file in ~/.local/state/auto-cpufreq/ (or your XDG_STATE_HOME location).
If a maintainer asks for the traditional hardware/system report, run auto-cpufreq --debug separately and save its terminal output. The historical --debug command requires root privileges and invokes cpufreqctl(), which can perform system setup; do not run it on a working production installation merely to collect routine read-only monitoring data. Review its implementation and effects before using it with sudo.
Share the Stats log and, when explicitly collected, the Debug text with the relevant error description, auto-cpufreq version and approximate collection time. A Python stack trace is recorded by optional diagnostics only when its trigger conditions occur, not in every session. Review and redact private paths and other identifying information before sharing.

The commands are complementary, not simultaneous: --stats --debug is rejected, and --diagnostic-log is only valid with exactly one of --stats, --monitor and --live. It cannot accompany update, installation, removal or power overrides. Do not use --live as a troubleshooting alternative to Stats: Live may change CPU power settings.

Overriding governor

sudo auto-cpufreq --force=governor

Force use of either the "powersave" or "performance" governor, or set to "reset" to go back to normal mode.

This overrides only the CPU governor. Other charger/battery profile settings continue to follow the detected power source.

Please note that any set override will persist even after reboot.

Overriding Turbo mode

sudo auto-cpufreq --turbo=mode

Force use of CPU turbo mode, if supported, with "never" or "always", or set to "auto" to automatically handle turbo mode. Please note that any set override will persist even after reboot.

Install - auto-cpufreq daemon

Necessary changes are made to the system over time and this process will continue across reboots. The daemon is deployed and started through the supported init system. Changes are made automatically and live stats are generated for monitoring purposes.

Install the daemon using CLI (after installing auto-cpufreq):

Installing the auto-cpufreq daemon using CLI is as simple as running the following command:

sudo auto-cpufreq --install

After the daemon is installed, auto-cpufreq is available as a binary and runs in the background. Its stats can be viewed by running: auto-cpufreq --stats

The daemon can also be installed from the GTK interface. See GUI.

auto-cpufreq daemon service

Installing the auto-cpufreq daemon also enables the associated service at boot and starts it immediately (equivalent to systemctl enable --now auto-cpufreq on systemd).

On systemd systems, the daemon's status can be seen by running:

systemctl status auto-cpufreq

If installed via Snap package, daemon status can be viewed as follows:

systemctl status snap.auto-cpufreq.service.service

Update - auto-cpufreq update

For source installations, the updater checks the latest published release, clones that exact release tag, and installs it through auto-cpufreq-installer. If the auto-cpufreq daemon was installed, the updater removes and reinstalls it; otherwise the daemon remains uninstalled. The updater does not install the development master branch.

The installer builds and verifies the new release as a separate generation before selecting it through /opt/auto-cpufreq/current. Download, daemon removal, installation, and final command failures stop the updater without reporting success; a candidate that fails before activation does not replace the active generation.

Update auto-cpufreq by running: sudo auto-cpufreq --update. By default, the selected release tag is cloned to a uniquely named staging directory under /opt/auto-cpufreq/source; the updater removes that staging directory after the attempt finishes.

Update and create the staging directory under a custom parent by running: sudo auto-cpufreq --update=/path/to/directory

Development checkouts are not advanced by --update. To replace a development installation while its daemon is installed, run sudo auto-cpufreq --remove, install the desired Git revision with sudo ./auto-cpufreq-installer --install, and then run sudo auto-cpufreq --install to deploy the daemon from the new generation.

Remove - auto-cpufreq daemon

The auto-cpufreq daemon and its service can be removed by running:

sudo auto-cpufreq --remove

This does, in part, the equivalent of systemctl stop auto-cpufreq && systemctl disable auto-cpufreq, but the above command should be used instead of using systemctl.

Removing the daemon does not uninstall the source-installed CLI or GUI. To remove the complete source installation, run sudo bash ./auto-cpufreq-installer --remove from an auto-cpufreq source directory.

If removal fails, address the reported error and retry the same command. On s6, an unfinished removal must complete before reinstalling the daemon. If the error identifies unrecognized source-install remnants or a preserved s6 removal directory, inspect and preserve any custom files before removing those remnants; they are not treated as successful cleanup.

Stats

If the daemon has been installed, live system information and the current optimization state can be viewed with:

auto-cpufreq --stats

In addition to CPU and battery telemetry, the stats interface reports the current Platform Profile, detected interface, control availability, available platform profiles, and provider information. CPU power controls such as the governor, EPP, EPB, HWP Dynamic Boost, and Turbo Boost are grouped separately under CPU Power State.

bluetooth_boot_off

Turn off Bluetooth on boot (only)! Bluetooth can still be turned on manually when needed. This option is executed during the installation of the auto-cpufreq daemon, but it can also be run independently without installing the daemon.

It prevents GNOME from automatically enabling Bluetooth on every reboot or after suspend/wake up even if you manually disable it, GNOME will turn it back on unless this option is used.

bluetooth_boot_on

Useful if you prefer Bluetooth to be enabled at boot time, especially after installing the auto-cpufreq daemon, which will disable it by default.

Intel HWP Dynamic Boost

On typical non-server Intel systems, the Linux intel_pstate driver starts HWP Dynamic Boost disabled. When hwp_dynamic_boost is not explicitly configured, auto-cpufreq keeps it disabled on battery power and enables it on AC/charger power on supported systems. Current upstream kernels may enable Dynamic Boost automatically on systems using the ACPI Enterprise Server or Performance Server profiles.

Dynamic Boost is detected through /sys/devices/system/cpu/intel_pstate/hwp_dynamic_boost; systems that do not expose this interface are left unchanged.

When disabling Dynamic Boost, auto-cpufreq applies that state before changing EPP. When enabling Dynamic Boost, EPP is applied first. To override the default policy, configure hwp_dynamic_boost in the charger and/or battery profiles; see 4: auto-cpufreq config file.

Platform Profiles

Linux Platform Profiles provide a standardized interface for selecting platform-wide power and performance policies exposed by the system firmware or platform driver. Unlike the CPU governor, EPP, or EPB, a platform profile may affect more than the CPU, including thermal behavior, fan policy, power limits, and other platform-specific components.

Platform Profile support depends on the hardware, firmware, kernel, and available platform driver. It can be present on laptops, desktops, mini PCs, and other systems. If no Platform Profile interface is detected, auto-cpufreq reports that state without attempting to configure it.

auto-cpufreq prefers the modern Linux Platform Profile class interface:

/sys/class/platform-profile/

The aggregate interface remains supported for compatibility and safe global control:

/sys/firmware/acpi/platform_profile

When only the aggregate interface is available, auto-cpufreq can still read and configure Platform Profiles. The aggregate interface reports the current profile and the available choices, but it does not expose a generic provider name. The normal reporting interfaces therefore identify the interface as Legacy and report that the provider name is not available from that ABI.

auto-cpufreq also reports whether Platform Profile control is available. If the current state can be observed but the available choices cannot be determined reliably, the profile remains visible but control is disabled. auto-cpufreq does not write an unvalidated profile value. This distinguishes a detected-but-not-safely-controllable interface from a system where no Platform Profile interface was detected at all.

The profile names are defined by the Linux Platform Profile ABI, but not every system supports every profile. The kernel reports the exact profiles available for the current machine, so users should not assume that values such as balanced, quiet, or performance are always available.

To see the profiles available on the current system, use:

auto-cpufreq --stats

or:

auto-cpufreq --pp

For example:

Platform Profile
Interface: Modern · Control: Available
Current profile: balanced
Available profiles (4): low-power, quiet, balanced, performance
Provider: example-platform-driver

The GTK interface displays the same information in its Platform Profile section. These reporting interfaces are informational; profile selection remains an advanced configuration option in auto-cpufreq.conf.

Platform Profiles can be configured independently for charger and battery operation:

[charger]
platform_profile = balanced

[battery]
platform_profile = quiet

Always choose a value reported in Available profiles on the target system. auto-cpufreq validates the requested profile against the profiles reported by the kernel before attempting to apply it.

By default, auto-cpufreq continuously restores the configured Platform Profile. This keeps the selected charger or battery policy authoritative even if the profile is changed manually.

This default behavior is equivalent to:

enforce_platform_profile = true

With:

enforce_platform_profile = false

auto-cpufreq applies the configured profile when switching between charger and battery policies, but does not continuously overwrite a manual profile change.

Modern kernels may expose more than one Platform Profile provider. auto-cpufreq reports each provider and its current profile. For global configuration, only profiles that can be safely applied across the platform are offered. If providers are currently using different profiles, the aggregate state may be reported as custom. auto-cpufreq does not arbitrarily modify only one provider when a safe global control path is unavailable.

custom can have different semantics depending on the kernel interface. With multiple providers, it may describe an aggregate state where providers are using different profiles rather than a profile that can be selected globally. auto-cpufreq therefore relies on the kernel-reported writable choices instead of maintaining its own fixed list of profile names.

Battery charging thresholds

Please note: Original implementor is looking for user input & testing to further improve this functionality. If you would like to help in this process, please refer to Looking for developers and co-maintainers.

As of v2.2.0, battery charging thresholds can be set in the config file. This enforces your battery to start and stop charging at defined values.

Supported devices

Lenovo ThinkPad (thinkpad_acpi)*
Lenovo IdeaPad (ideapad_acpi)*
Lenovo Laptop (ideapad_laptop)*
Lenovo Legion (ideapad_laptop)*
ASUS :Laptops (asus_wmi)*

Please note, your laptop must have an installed ACPI kernel driver specific to the manufacturer. To check if you have the correct module installed and loaded run lsmod [module]

Additionally, you should make sure that you have no other software running that may conflict with auto-cpufreq's battery threshold management (e.g., GNOME's Preserve Battery Health option). Using both at the same time will lead to conflicts and to your battery potentially never charging.

To request that your device be supported, please open an issue. In your issue, make us aware of the driver that works with your laptop

Battery config

Edit the config at /etc/auto-cpufreq.conf

Example config for battery (already part of example config file)

[battery]
enable_thresholds = true
start_threshold = 20
stop_threshold = 80

You will need to specify both start_threshold AND stop_threshold in most cases. For these changes to have an effect, you will need to restart the daemon:

sudo systemctl restart auto-cpufreq.service

See more here on the kernel doc pages: docs.kernel.org

A few notes about these battery config options

When you remove/uninstall the auto-cpufreq daemon, the last applied settings for battery thresholds will still apply. You might need to manually set these yourself to whatever default they were before. E.g. (as sudo):

printf '0\n' | sudo tee /sys/class/power_supply/BAT0/charge_start_threshold
printf '100\n' | sudo tee /sys/class/power_supply/BAT0/charge_stop_threshold

Ideapad conservation mode

This works only with laptops that have the ideapad_laptop kernel module.

add ideapad_laptop_conservation_mode = true to your auto-cpufreq.conf file

[battery]
ideapad_laptop_conservation_mode = true

This is a special mode which limits the maximum charge level of the battery to around 60-80% depending on the model.

Ignoring power supplies

During automatic detection, auto-cpufreq ignores power supplies marked with scope = Device when selecting the system battery or determining whether the system is externally powered. This prevents peripherals such as controllers or headphones from affecting power-profile decisions when the kernel exposes their scope correctly.

If a power supply that should be ignored does not expose scope = Device, or if you want to exclude it explicitly, add its name under [power_supply_ignore_list].

Available power supplies can be listed with:

ls /sys/class/power_supply/

For example:

[power_supply_ignore_list]
peripheral = power_supply_name

Troubleshooting

Q: If after installing auto-cpufreq you're (still) experiencing:

high CPU temperatures
CPU not scaling to minimum/maximum frequencies
suboptimal CPU performance
turbo mode not available

A: If you're using the intel_pstate or amd-pstate CPU management driver, consider acpi-cpufreq only if your hardware and kernel support it; switching drivers is not a universal fix.

On systems using GRUB, the kernel parameters can be changed in GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub. For instance:

    sudo nano /etc/default/grub
    # make sure you have nano installed, or you can use your favorite text editor

For Intel users:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash intel_pstate=disable"

For AMD users:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash initcall_blacklist=amd_pstate_init amd_pstate.enable=0"

Once you have made the necessary changes to the GRUB configuration file, you can update GRUB by running sudo update-grub on Debian/Ubuntu, sudo grub-mkconfig -o /boot/grub/grub.cfg on Arch Linux, or one of the following on Fedora:

    sudo grub2-mkconfig -o /etc/grub2.cfg

    sudo grub2-mkconfig -o /etc/grub2-efi.cfg

    sudo grub2-mkconfig -o /boot/grub2/grub.cfg
    # legacy boot method

For systemd-boot users:

    sudo nano /etc/kernel/cmdline
    # make sure you have nano installed, or you can use your favorite text editor

For Intel users:

quiet splash intel_pstate=disable

For AMD users:

quiet splash initcall_blacklist=amd_pstate_init amd_pstate.enable=0

After editing the cmdline file, regenerate boot entries using your distribution's documented procedure (sudo reinstall-kernels on distributions that provide it).

Q: If auto-cpufreq-gtk doesn't launch with exit code 1 (Workaround)

A: Try launching it with env -i XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR auto-cpufreq-gtk and add it to /usr/share/applications/auto-cpufreq-gtk.desktop if it works.

AUR

If the AUR installer does not work for your system, fallback to auto-cpufreq-installer and open an issue.

Discussion:

Blogpost: auto-cpufreq - Automatic CPU speed & power optimizer for Linux

Donate

Showing your support and appreciation for the auto-cpufreq project can be done in two ways:

Financial donation
Code contribution

Financial donation

If auto-cpufreq helped you out and you find it useful, show your appreciation by donating (any amount) to the project!

Become Github Sponsor

Become a sponsor to Adnan Hodzic on Github to acknowledge my efforts and help project's further open source development.

pump.fun

Auto-cpufreq ($CPUFREQ) on pump.fun

Pump.fun Solana address: 6Bo3JHdnsiuJcDmHeApaUhTgtE1NNtBdZ3uyaL4ypump

Please note: This token was created independently by third-party community members. auto-cpufreq and its maintainers are not involved in its creation, management, or price activity. This listing strictly allows the maintainer to collect GitHub protocol-allocated trading rewards as open-source sponsorship. This is not financial advice or an endorsement, please be aware of the high risks involved in meme coin trading and always do your own research.

BitCoin

Bitcoin address: bc1qlncmgdjyqy8pe4gad4k2s6xtyr8f2r3ehrnl87

PayPal

Code contribution

Other ways of supporting the project consist of making a code or documentation contribution. If you have an idea for a new feature or you want to implement some of the existing feature requests or fix some of the bugs & issues, please make your changes and submit a pull request. I'll be glad to review it and, if your changes are accepted, you'll be credited on the releases page.

Please note: auto-cpufreq is looking for co-maintainers & open source developers to help shape the future of the project!

auto-cpufreq

Looking for developers and co-maintainers

Index

Why do I need auto-cpufreq?

Supported architectures and devices

Features

Installing auto-cpufreq

auto-cpufreq-installer

Debian repositories (.deb package)

Snap Store

AUR package (Arch based distributions)

Gentoo Linux (GURU Repository)

NixOS

Installation (development mode only)

Post-installation

Configuring auto-cpufreq

1: power_helper.py script (Snap package install only)

2: --force governor override

3: --turbo mode override

4: auto-cpufreq config file

Example config file contents

How to run auto-cpufreq

auto-cpufreq modes and options

Monitor

Live

GUI

GTK debug logging

Optional terminal diagnostics

Collecting a complete troubleshooting report

Overriding governor

Overriding Turbo mode

Install - auto-cpufreq daemon

Update - auto-cpufreq update

Remove - auto-cpufreq daemon

Stats

bluetooth_boot_off

bluetooth_boot_on

Intel HWP Dynamic Boost

Platform Profiles

Battery charging thresholds

Supported devices

Battery config

A few notes about these battery config options

Ideapad conservation mode

Ignoring power supplies

Troubleshooting

AUR

Discussion:

Donate

Financial donation

Become Github Sponsor

pump.fun

BitCoin

PayPal

Code contribution

2: `--force` governor override

3: `--turbo` mode override