# auto-cpufreq: a daemon that swaps CPU governors based on battery state > A Python daemon that watches battery, temperature and load, then moves the CPU between performance and powersave on its own. It is deliberately a TLP replacement, and it says so. **AdnanHodzic/auto-cpufreq** — Automatic CPU speed & power optimizer for Linux - Repository: https://github.com/AdnanHodzic/auto-cpufreq - Website: https://foolcontrol.org/?p=4603 - Stars: 7,856 · Forks: 361 - Language: Python - License: GPL-3.0 - Published: 2026-10-06 · Updated: 2026-10-06 · Language: en - Canonical page: https://hysenlabs.com/projects/adnanhodzic-auto-cpufreq ## The problem it names is a governor, not a missing daemon The README puts the problem plainly: on a Linux laptop the CPU can sit on the `performance` governor with turbo boost enabled whether or not the machine is plugged into a wall, and that costs battery. Two older approaches are called out by name. `indicator-cpufreq` and `cpufreq` both work but need manual action every time you unplug, which the README describes as cumbersome. TLP does the automation, and the author used it for years, but it can also create its own problems, with losing turbo boost named specifically. So the design goal is a tool that changes CPU frequency settings automatically while letting the kernel do the heavy lifting. That phrase is doing real work. auto-cpufreq is not a scheduler and does not implement its own frequency policy; it moves between the governors the kernel already exposes and adjusts the boost and platform profile settings around them. The scope is bounded in another way. Only devices with an Intel, AMD or ARM CPU are supported, and while the tool was built for laptops the README says desktops and servers should also work if you want lower power consumption. The topic list on the repository matches that framing: `laptop`, `battery`, `governor`, `turbo`, `daemon`, `monitoring`. ## Install paths, from a shell script to a Nix flake The README documents five routes, which is unusual for a small Python tool. The first is `auto-cpufreq-installer`, a script sitting at the repository root. The second is the Snap Store, which comes with an extra configuration step: a `power_helper.py` script that has to be edited for the Snap package only, because the sandbox otherwise blocks the sysfs writes the tool needs. The third is an AUR package for Arch-based distributions, the fourth is NixOS, and the fifth is a developer-only path. The tree backs the packaging story up with a `snap/` directory, a `flake.nix` and `flake.lock`, a `nix/` directory, and a separate `auto-cpufreq.conf-example.nix` alongside the plain `auto-cpufreq.conf-example`. The developer path runs through Poetry, and `pyproject.toml` defines the whole dependency set: ```toml [tool.poetry.dependencies] python = ">=3.9, <4.0" psutil = ">=6.0.0,<8.0.0" click = "^8.1.0" distro = "^1.8.0" ``` Two entries in that list explain a lot about the tool. `distro` is there because battery thresholds are laptop-model specific and the project reads manufacturer identifiers to decide whether a charge limit applies. `urwid` at `^3.0.2` is the terminal UI library, which v3.0.0 migrated to after closing the older version. The version range on Python is wide, from 3.9 up to but not including 4.0. ## Entry points are two console scripts `pyproject.toml` registers two commands, and which one you use decides whether you need GTK at all: ```toml [tool.poetry.scripts] auto-cpufreq = "auto_cpufreq.bin.auto_cpufreq:main" auto-cpufreq-gtk = "auto_cpufreq.bin.auto_cpufreq_gtk:main" ``` The CLI entry is `auto-cpufreq`; the GTK one is `auto-cpufreq-gtk`. `PyGObject` is marked optional in the dependency list and is pulled in through a `gui` extra, so a terminal-only install does not need the GTK stack. That matters because v2.6.0 and v3.0.0 both carry dependency fixes for it, including a fix for `Dependency 'girepository-2.0' is required but not found` and a fix for installation on Pop!_OS. If the GUI will not start, the project documents a workaround in the README for the exit code 1 case, which is the sort of thing that only gets written down after enough people hit it. The packages listed are `./auto_cpufreq` and `./auto_cpufreq/gui`, so the GUI is a subpackage rather than a separate distribution. Versioning is handled by `poetry-dynamic-versioning` reading from git, formatting versions as `v{base}+{commit}`, which is why a source checkout reports a different version than a release. ## Modes: monitor, live, stats and the two overrides The README's own index lists the modes, which is a fast way to see the surface. `monitor` shows battery, frequency, usage and temperature. `live` is the TUI, and v3.0.0 fixed `auto-cpufreq --monitor` reporting the CPU frequency scaling section wrongly, so the two views are not identical. `stats` prints a one-shot report, and the README includes a screenshot of that output. Then there are the two overrides. `--force` pins the governor regardless of what the daemon would have chosen, and `--turbo` forces turbo mode on or off. v3.0.0 added the ability to override turbo via CLI and GUI, closing issue #604, and v3.1.0 fixed a related bug where frequency limits were not re-applied after a turbo update, which is the kind of ordering mistake that only shows up on hardware that actually toggles boost. The daemon lifecycle commands follow in the same index: install auto-cpufreq daemon, update, remove. `auto-cpufreq update` exists as a first-class command, which tells you the project expects to be installed system-wide and periodically replaced. There is also `bluetooth_boot_off` and `bluetooth_boot_on`, functionality added in v2.6.0 to close issues #92, #451 and #673, and moved into the GUI in v3.1.0. ## Laptop-specific hardware features are where the value sits Three features in the README are specific to real hardware rather than generic power tuning, and each one is where the maintenance work is visible. Intel HWP Dynamic Boost is supported, which means the daemon can work with the hardware's own boost algorithm instead of fighting it. Platform Profiles are handled too, and v3.1.0 added a new `enforce_platform_profile` configuration option. That release also fixed an NVIDIA GPU wake issue by only setting the platform profile when it differs from the current one, which is the classic fix for a driver that resets state on resume. Battery charging thresholds are the biggest chunk. The README keeps a Supported Devices list, a Battery config section, and a section on ignoring power supplies. v3.0.0 added the ability to specify the battery device in config, improved battery path detection after a path error, and added fallback battery threshold file paths. v3.1.0 extended `conservation_mode` detection to more Lenovo models. The Lenovo limitation is the clearest signal about how this works: conservative charging mode has to be supported in firmware, so the tool has to recognise the model and check. v3.1.0 also added support for systems with no `/sys/class/power_supply/` directory in sysfs and fixed power consumption calculation when the `power_now` file is missing. That is a desktop and server fix, and it is a good sign about how the failures get found. ## Running two CPU managers at once is the documented mistake The README is unusually direct about this. auto-cpufreq aims to replace TLP in terms of functionality, and after installing it the recommendation is to remove TLP. Using both for the same job, setting CPU frequencies, leads to results the author describes as unwanted, with overheating named as one. There is a link to a discussion on using the two in tandem for people who know what they are doing, which is the correct way to handle the case where you need TLP for something auto-cpufreq does not do. One tool that does not conflict is `thermald`, and the README calls it even recommended to run alongside. That asymmetry is the whole design in one line: thermald manages CPU frequency by staying out of the way, auto-cpufreq manages it by moving governors. The project state is healthy. It is not archived, the last push was on 2026-09-12, and v3.1.0 shipped on 2026-07-26 with the GUI monitoring mode, the bluetooth controls, the `enforce_platform_profile` option and a batch of fixes. The README also asks for co-maintainers, which is worth weighing if you plan to depend on it: a single-maintainer utility that writes to sysfs is a different risk profile from a small kernel-adjacent tool with several people reviewing changes. Licence is GPL-3.0-or-later, and the author hosts the project blog at foolcontrol.org alongside the repository. ## Conclusion auto-cpufreq is for the laptop that sits unplugged for hours and runs hot and flat under a default governor. It is not a tuning tool for a desktop and it is not a replacement for thermald, which the README explicitly says can run alongside it. The mechanism is narrow on purpose: watch sysfs, change the governor, throttle turbo, and let the kernel's own scaling do the rest. Read `auto-cpufreq.conf-example` before the first run, remove TLP rather than layering the two, and check `auto-cpufreq --stats` afterwards, since v3.1.0 shipped a fix for wrong EPP and EBP fallback profiles in exactly that output. ## FAQ ### What does auto-cpufreq do? It monitors laptop battery state, CPU usage, CPU temperature and system load, then changes CPU frequency settings so the governor and turbo mode match whether the machine is plugged in. The goal is longer battery life without giving up turbo when you are on mains. It supports Intel, AMD and ARM CPUs and is built around letting the kernel do the frequency scaling. ### Is auto-cpufreq better than TLP? The project positions itself as a TLP replacement rather than a companion to it, and the README recommends removing TLP after installing auto-cpufreq. The stated reason is that running both to set CPU frequencies causes unwanted results such as overheating. TLP is also described as a tool the author used for years that could lose turbo boost, which is what auto-cpufreq is designed to avoid. ### How do I install auto-cpufreq? The README lists five options: the `auto-cpufreq-installer` script in the repository, the Snap Store, an AUR package for Arch-based distributions, NixOS, and a development install. Snap installs need one extra step, editing `power_helper.py`, because of sandbox restrictions on the sysfs writes the daemon performs. Only Intel, AMD and ARM CPUs are supported. ### How can I use auto-cpufreq in Arch Linux? Arch-based distributions are served by the AUR package listed in the README's install section. The repository also keeps a troubleshooting section specifically for AUR, so that is the place to look when the package builds or starts incorrectly. Arch users on Nix can use the `flake.nix` and the separate `auto-cpufreq.conf-example.nix` instead. ## Sources - [AdnanHodzic/auto-cpufreq on GitHub](https://github.com/AdnanHodzic/auto-cpufreq) - [License: GPL-3.0](https://github.com/AdnanHodzic/auto-cpufreq/blob/master/LICENSE) - [Project website](https://foolcontrol.org/?p=4603) - [README](https://github.com/AdnanHodzic/auto-cpufreq/blob/master/README.md) - [Releases](https://github.com/AdnanHodzic/auto-cpufreq/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/adnanhodzic-auto-cpufreq