Skip to main content

pycpufreq

CI Status PyPI version Python Versions License uv


pycpufreq is a modern Python library and CLI utility to monitor and configure CPU scaling frequencies and Intel Turbo Boost via Linux sysfs (/sys/devices/system/cpu).

✨ Key Features

  • Query CPU Frequencies: Retrieve minimum, maximum, current, and scaling CPU frequencies.
  • Multicore Scaling Configuration: Safely set scaling maximum frequency across all present CPU cores (cpu0, cpu1, ...).
  • Intel Turbo Boost Toggle: Enable or disable turbo state on Intel processors through intel_pstate/no_turbo.
  • Target Frequency Validation: CLI validates custom frequencies against real hardware bounds ($f_{min} \le f_{target} \le f_{max}$).
  • Standard Internationalization (gettext): Multi-language support (English, Spanish, French, Romanian, Russian, Chinese, Hindi).
  • Modern Packaging with uv & poethepoet: High-performance task runner, dependency management and zero-dependency runtime.

📦 Installation

Install with uv:

uv add pycpufreq

Or using pip:

pip install pycpufreq

🚀 Quick Start

Python Library

from pycpufreq import (
    is_cpufreq_configured,
    sys_get_cpu_max_freq,
    sys_get_cpu_min_freq,
    sys_get_cpu_current_freq,
    sys_set_cpu_max_scaling_freq,
    sys_set_cpu_turbo,
)

if is_cpufreq_configured():
    print(f"Max Frequency:     {sys_get_cpu_max_freq()} kHz")
    print(f"Min Frequency:     {sys_get_cpu_min_freq()} kHz")
    print(f"Current Frequency: {sys_get_cpu_current_freq()} kHz")

    # Set scaling frequency (requires write permissions to sysfs):
    # sys_set_cpu_max_scaling_freq(2400000)

    # Enable or disable Turbo boost:
    # sys_set_cpu_turbo(True)

Command Line Interface (CLI)

Run the CLI directly:

# Display CPU stats, run dynamic scaling test and restore maximum frequency:
pycpufreq

# Run and leave CPU at a validated target frequency (e.g. 2400000 kHz):
pycpufreq 2400000

# Show help & options:
pycpufreq --help

Or via uv:

uv run pycpufreq

🛠️ Development & Tasks

This project uses poethepoet to streamline development tasks.

Run Tests

poe test
# or directly:
uv run pytest

Update Translations

Extract translatable strings, update catalogs and compile binary .mo files:

poe translate

Release Checklist

Print release steps and commands for tag, build and publish:

poe release

📄 License

Distributed under the terms of the GNU General Public License v3 or later (GPL-3.0-or-later).

Metadata

Release files for pycpufreq 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pycpufreq 1.0.0
File Size Uploaded Provenance Actions
pycpufreq-1.0.0.tar.gz 10.1 kB Without provenance Details for pycpufreq-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pycpufreq 1.0.0
File Interpreter ABI Platform Actions
pycpufreq-1.0.0-py3-none-any.whl Python 3 none any Details for pycpufreq-1.0.0-py3-none-any.whl

Total release size: 33.8 kB

Release files / pycpufreq-1.0.0.tar.gz

Download URL pycpufreq-1.0.0.tar.gz
Size 10.1 kB
Tags Source
SHA-256 checksum
How to use checksums
931b2f70e74b6c2e4c643d363cfc8ae71400926e53c041175affc2de1065cca4
BLAKE2b-256 checksum
How to use checksums
391c8e69c93485c6d5252197b72b5dc9b72eda67c2f7d0781ab00f193a34167f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.5.1 CPython/3.14.10 Linux/7.3.0-gentoo

Release files / pycpufreq-1.0.0-py3-none-any.whl

Download URL pycpufreq-1.0.0-py3-none-any.whl
Size 23.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4e2bb741d2ed12b02277c8499e332e075367ebdd7ea47d3c4c6184b2b22a6b38
BLAKE2b-256 checksum
How to use checksums
ba5166b8b65ee07a50e54e4f08ffa52429572ea9bd68eeee0f8bfad8fccfc66f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.5.1 CPython/3.14.10 Linux/7.3.0-gentoo

Security for pycpufreq 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page