Skip to main content

host-pressure

한국어

Read what the machine is doing right now, and whether it has room, in one line.

$ pipx install host-pressure
$ host-pressure
CPU 15% MEM 76% SWAP 1.4G pressure normal

No subprocess. No dependency. No daemon. The readings come from the kernel itself: Mach and sysctl through ctypes on macOS, /proc on Linux, kernel32 on Windows.

Why

  • A verdict, not a number. host-pressure check prints ok, busy or overloaded with the readings that decided it, and exits 0, 1 or 2. host-pressure wait --until ok --timeout 120 blocks a script or an agent until the machine has room again.
  • Three readings psutil does not have. The macOS memory pressure level (the kernel's own signal that Activity Monitor shows), Linux pressure stall information for CPU, memory and IO (/proc/pressure), and the macOS thermal state. psutil 7.2 reports memory percent, swap bytes and temperatures per sensor; it reports no pressure level, no PSI and no thermal state.
  • CPU that admits it needs two samples. A utilisation percentage is a difference between two counter reads, never one. The previous counters are kept per consumer id, so a status line pays nothing; --sample 0.5 takes both samples in one call and does not touch that state.
  • One line for a status bar. --format 'CPU {cpu} MEM {mem}' prints only what your bar needs, and every placeholder already carries its unit.
  • Nothing to install twice. Pure standard library. pipx, uvx or a ten-line import in your own program.
$ host-pressure --all
CPU 13% MEM 76% SWAP 1.4G pressure normal LOAD 2.94 3.49 3.53 DISK / 44% THERM nominal

On a Linux server with pressure stall information, the same command:

$ host-pressure --all
CPU 57% MEM 12% SWAP 0B pressure normal LOAD 0.92 0.52 0.57 DISK / 66% PSI cpu 1.5 mem 0.0 io 0.1

Install

$ pipx install host-pressure     # recommended: isolated, on PATH
$ uvx host-pressure              # or run without installing
$ pip install host-pressure      # inside a project

Python 3.9 or newer, no dependency, no build step beyond the wheel.

Editions

One PyPI name ships both editions:

  • Python (src/host_pressure/): pure standard library, import host_pressure works everywhere Python 3.9+ runs.
  • Rust (rust/): the same CLI, the same --json keys and exit codes. pipx install host-pressure installs the fast Rust binary as the host-pressure command while the pure-Python package stays importable (maturin bindings = "bin" with python-source = "src"; cargo install --path rust also works).

The CPU baseline state file is shared: the same path ($XDG_STATE_HOME/host-pressure/cpu_ticks_<consumer>.json) and the same JSON format, so the two editions can alternate under one --consumer id. bash rust/parity.sh checks the parity (same flags, normalised volatile numbers).

Measured 2026-11-17, 20-run loop, --no-sample baseline path:

Host Python Rust Speedup
M5 macOS arm64 74.5 ms 9.3 ms 8.0x
A1 Ubuntu 24.04 arm64 73.7 ms 2.1 ms 35x

--sample 0.1 is sleep-dominated and similar in both (the kernel publishes CPU counters in batches, stretching short windows by up to 1 s). Release binary: 706 KB (macOS arm64), 850 KB (Linux arm64). Peak RSS: Rust ~2 MB vs Python ~13-16 MB. Windows Rust is untested (no toolchain on the laptop); the Python edition there was verified earlier.

Usage

One line

$ host-pressure
CPU 15% MEM 76% SWAP 1.4G pressure normal

CPU, MEM and SWAP are n/a when the platform cannot answer, and pressure is normal, warning, critical or unknown. Nothing is invented to fill a gap.

Everything at once

$ host-pressure --all
CPU 13% MEM 76% SWAP 1.4G pressure normal LOAD 2.94 3.49 3.53 DISK / 44% THERM nominal

--all appends the load average, one DISK <mount> <percent> per --disk mount, the thermal state, the battery, and the PSI stall percentages where the kernel has them. --disk /Volumes/work --disk / reads two mounts; the first one also fills the {disk} placeholder.

Templates for a status bar

$ host-pressure --format 'CPU {cpu} MEM {mem} | load {load1}'
CPU 8% MEM 76% | load 2.94
$ host-pressure --format 'cpu {cpu} mem {mem} swap {swap} {level}'
cpu 20% mem 73% swap 1.4G ok

host-pressure --format-help lists every placeholder. Each value already carries its unit ({cpu} → 16%, {swap} → 1.5G), so a template never needs to add % itself. An unknown name is a usage error, not an empty string.

Machine readable

$ host-pressure --json
{
  "observedAt": "2026-11-17T08:24:55.523683+00:00",
  "os": "darwin",
  "hostname": "<host name>",
  "ncpu": 18,
  "cpuPercent": 14.3,
  "cpuSource": "baseline",
  "memoryPercent": 75.6,
  "memoryTotalBytes": 68719476736,
  "memoryUsedBytes": 51943424000,
  "swapBytes": 1516306432,
  "swapTotalBytes": 3221225472,
  "pressure": "normal",
  "pressureSource": "macos",
  ...
  "verdict": {
    "level": "ok",
    "reasons": []
  }
}

cpuSource says where the CPU number came from: baseline (the counter delta since the previous call with this consumer id) or sample (a window inside this call), and null when it has neither. pressureSource says which signal decided pressure: macos, psi-avg60, memavailable or memoryload.

A verdict, with exit codes

$ host-pressure check
ok
$ echo $?
0

When the machine is under pressure, the level and the reasons come on one line:

$ host-pressure check --memory-busy 10
busy: memory 75.7% >= 10%
$ echo $?
1

overloaded exits 2. --json prints the same result as {"level": ..., "reasons": [...]}. Reasons are deliberately literal: the reading, the threshold, and nothing else.

Wait for room

$ host-pressure wait --until ok --timeout 120
ok

wait polls every --interval seconds (2 by default), takes a fresh --sample window each time (0.2 s), and returns as soon as the level is at or better than --until. A timeout exits 75 (EX_TEMPFAIL) and prints the last verdict on stderr, so a caller can tell "still busy" from "broken".

$ host-pressure wait --until busy --timeout 30 && make -j8

Watch

$ host-pressure --watch 2
CPU 45% MEM 73% SWAP 1.4G pressure normal
CPU 21% MEM 74% SWAP 1.4G pressure normal
CPU 16% MEM 74% SWAP 1.4G pressure normal

--watch repeats every N seconds until interrupted. With --json it prints one JSON object per line, so it pipes into anything that reads JSONL.

CPU: baseline or sample

CPU needs two counter reads. There are two ways to get them, and the tool never hides which one it used.

Mode Flag What it costs When to use
Baseline default nothing; one stat and one small file write a status line, a cron, a daemon that calls every N seconds
Sample --sample 0.5 one sleep of the given length one run that must print a number now
No wait --no-sample nothing, prints n/a while the baseline is cold a strict latency budget

The baseline is kept per --consumer id under $XDG_STATE_HOME/host-pressure, so two tools never overwrite each other's interval. The first call for a new consumer reports n/a; host-pressure with no flags fills that gap once with a 0.3 s sample, which is why the very first run of a fresh install takes a third of a second.

Options

Flag Meaning Default
--json print the whole reading as JSON off
--format TEMPLATE print a custom line off
--format-help list the template placeholders —
--all add load, disk, thermal, battery and PSI off
--watch N repeat every N seconds off
--disk MOUNT read this mount, repeatable /
--sample N take both CPU samples in this call off
--no-sample never wait for a CPU sample off
--consumer ID name of this writer's CPU baseline default
--state-dir DIR where CPU baselines are kept $XDG_STATE_HOME/host-pressure
--config PATH threshold file $XDG_CONFIG_HOME/host-pressure/config.json
--cpu-busy, --cpu-overloaded CPU thresholds, percent 80 / 95
--memory-busy, --memory-overloaded memory thresholds, percent 85 / 95
--load-busy, --load-overloaded load average per CPU core 1 / 2
--disk-busy, --disk-overloaded disk used thresholds, percent 90 / 97
--swap-busy-gb, --swap-overloaded-gb used swap thresholds, GiB off

wait also takes --until ok|busy|overloaded, --timeout SECONDS (120) and --interval SECONDS (2).

Thresholds

Defaults can be changed for one run with the flags above, for a shell with HOST_PRESSURE_<KEY>, or permanently in $XDG_CONFIG_HOME/host-pressure/config.json:

{
  "cpu_busy": 70,
  "memory_busy": 80,
  "load_overloaded": 3,
  "disk_busy": 85,
  "swap_overloaded_gb": 8
}

The keys are the flag names in upper snake case: cpu_busy, cpu_overloaded, memory_busy, memory_overloaded, load_busy, load_overloaded, disk_busy, disk_overloaded, swap_busy_gb, swap_overloaded_gb, psi_cpu_busy, psi_cpu_overloaded, psi_memory_busy, psi_memory_overloaded, psi_io_busy, psi_io_overloaded. A mistyped key is an error that lists the valid ones, not a silently ignored line.

Two rules are fixed, because the kernel already decided them: the macOS memory pressure level (warning → busy, critical → overloaded) and the thermal state (fair → busy, serious or critical → overloaded).

Environment variable Meaning
HOST_PRESSURE_CONFIG threshold file path
HOST_PRESSURE_STATE_DIR CPU baseline directory
HOST_PRESSURE_<KEY> one threshold, e.g. HOST_PRESSURE_CPU_BUSY=70

Python

import host_pressure

host_pressure.read()                    # every reading, as a dict
host_pressure.read(sample=0.5)          # CPU from a 0.5 s window in this call
host_pressure.read(mounts=["/", "/data"])
host_pressure.verdict()                 # {"level": "ok", "reasons": []}
host_pressure.verdict(thresholds=host_pressure.Thresholds(memory_busy=50))
host_pressure.sample_cpu_percent(0.2)   # CPU only, and only this

read() never spawns a process and never sleeps unless you pass sample. Pass consumer_id="my-tool" when several programs call it from the same account: each id owns one baseline file and one interval.

>>> import host_pressure
>>> host_pressure.verdict(thresholds=host_pressure.Thresholds(memory_busy=50))
{'level': 'busy', 'reasons': ['memory 72.8% >= 50%']}

What it reads per platform

Reading macOS Linux Windows
CPU host_statistics (Mach) /proc/stat GetSystemTimes
Memory Activity Monitor formula: app + wired + compressed MemAvailable GlobalMemoryStatusEx
Swap vm.swapusage SwapTotal - SwapFree page file in use (NtQuerySystemInformation)
Pressure kern.memorystatus_vm_pressure_level /proc/pressure (PSI), MemAvailable if absent memory load
Load average, CPU count getloadavg, os.cpu_count same CPU count only
Thermal NSProcessInfo.thermalState warmest /sys/class/thermal zone —
Battery IOKit power sources /sys/class/power_supply GetSystemPowerStatus
Disk statvfs statvfs GetDiskFreeSpaceExW
Uptime kern.boottime /proc/uptime GetTickCount64

Limits

  • Tested on macOS 27 arm64 (18-core desktop), Ubuntu 24.04 arm64 (2 vCPU server) and Windows 11 x64 (laptop, Python 3.10), Python 3.9 and 3.12 on the first two. On Windows, memory and page-file numbers were checked against Win32_OperatingSystem and Win32_PageFileUsage. Every example above is a real output from one of those two machines.
  • Windows has no load average or thermal reading; pressure there is derived from memory load.
  • Battery is untested. Both test machines have no battery, so only the "no battery present" path was exercised; the reading itself (IOKit, /sys/class/power_supply, GetSystemPowerStatus) has not been seen returning a real percentage.
  • macOS thermal uses NSProcessInfo.thermalState, reached through the Objective-C runtime with ctypes. The API is public, the bridge is ours, and it can return null if Foundation is not loadable.
  • Linux thermal is the warmest thermal zone, when the kernel exposes one; many virtual machines expose none, so the reading is null there.
  • A short sample can wait. The kernel publishes CPU counters in batches (about once a second on Apple silicon), so a --sample window shorter than that is stretched by at most one second until the counters move. --no-sample never waits and prints n/a instead.
  • The baseline window is the gap between calls. Two runs inside the same second measure almost nothing; the reading is noisy by nature at that interval. Use --sample when the window must be exact.
  • Swap is not a pressure signal on macOS. A Mac with light use can sit at gigabytes of swap for days, so the swap thresholds are off by default and the memory pressure level is the signal to trust.

For agents

AGENTS.md tells an AI agent when to reach for this tool, which command answers which question, how to read the exit codes, and what not to do with it.

MIT licensed.

Metadata

Release files for host-pressure 0.1.0

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

Built distributions (wheels)

Table of built distributions (wheels) for host-pressure 0.1.0
File Actions
host_pressure-0.1.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for host_pressure-0.1.0-py3-none-win_amd64.whl
host_pressure-0.1.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for host_pressure-0.1.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
host_pressure-0.1.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for host_pressure-0.1.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
host_pressure-0.1.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for host_pressure-0.1.0-py3-none-macosx_11_0_arm64.whl
host_pressure-0.1.0-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for host_pressure-0.1.0-py3-none-macosx_10_12_x86_64.whl

Total release size: 1.6 MB

Release files / host_pressure-0.1.0-py3-none-win_amd64.whl

Download URL host_pressure-0.1.0-py3-none-win_amd64.whl
Size 251.6 kB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
9a112a71eee695d582d739203e81ea5da89f2037452b50c290942bc4c2a46c6f
BLAKE2b-256 checksum
How to use checksums
ce39f9eac077e67eaaea54a826770ed8832b38e1a675d63c5193f6f228baa329
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via maturin/1.16.0

Release files / host_pressure-0.1.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL host_pressure-0.1.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 365.7 kB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
a9627d081115cb8c960cb40fe37616e2ab2e66f46d076d6e205b9e4b7f94d466
BLAKE2b-256 checksum
How to use checksums
f76262cc81a7360f207e55e44120d533fee35e878ec83814655a2af5557ca77b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via maturin/1.16.0

Release files / host_pressure-0.1.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL host_pressure-0.1.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 350.3 kB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
3631155bbc233fc3f5c4d5d26722a19c7e81c2404acde281059ee75c438c4318
BLAKE2b-256 checksum
How to use checksums
563bc842b51104bfad3b0505d365b0066bac49435ba3212def01a27e065e31c6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via maturin/1.16.0

Release files / host_pressure-0.1.0-py3-none-macosx_11_0_arm64.whl

Download URL host_pressure-0.1.0-py3-none-macosx_11_0_arm64.whl
Size 320.4 kB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
fe270565da139e555de7b107d2b35abf6672af0bf14c641b0e803566dd594fc4
BLAKE2b-256 checksum
How to use checksums
6360d355f132089be8edfe216adeb2b74c8a2f70f5ab0768be5f0f99ab9dbfa0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Release files / host_pressure-0.1.0-py3-none-macosx_10_12_x86_64.whl

Download URL host_pressure-0.1.0-py3-none-macosx_10_12_x86_64.whl
Size 329.8 kB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
51313ba2c20358db7daeba63b3cd6d7cf26cd2689359913aa1f96b83a1b6f43e
BLAKE2b-256 checksum
How to use checksums
306fa90744cbf53a97573584143be0ea969935a0096127273d7130ccacf39abd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via maturin/1.16.0

Security for host-pressure 0.1.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.

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