Skip to content

A GPU task manager for Windows, Linux, and WSL: per-process VRAM, GPU activity, and LLM model/KV-cache insights (Windows AMD and NVIDIA).

Python

Add system RAM and CPU panel and per-process RAM/CPU% columns

Michael Erickson6e8bf810ea11
diff --git a/README.md b/README.md
index 844aee8..2e7cb3c 100644
--- a/README.md
+++ b/README.md
@@ -656,6 +656,7 @@ Identification is designed to stay cheap. Measured on one Windows machine:
| macOS: `ioreg` device stats + Metal clients | ~10 ms | Every refresh |
| macOS: memory-map scan (`proc_pidinfo` region walk) | ~4 ms per process | Same policy as the memory-map scan above |
| macOS: `footprint` GPU memory | ~70 ms per process, background thread | Busy and new processes every ~2 s, idle ones every 30 s (54 runs in 40 s with 27 GPU processes, M4 Mac mini) |
+| System RAM/CPU panel (fork): Windows `NtQuerySystemInformation` process list + psutil totals | ~6 ms for ~480 processes (Windows 11, i9-13900K) | Every refresh; `--no-system` turns it off. psutil per-process `memory_info`/`cpu_times` took ~1 s per pass here, so it is only the non-Windows fallback |
With two llama-servers running, a steady refresh costs roughly 15-30 ms of CPU (about 340 ms before
process details were cached).
diff --git a/src/gputaskman/app.py b/src/gputaskman/app.py
index c8e68e3..b40450c 100644
--- a/src/gputaskman/app.py
+++ b/src/gputaskman/app.py
@@ -17,6 +17,7 @@ from textual.screen import ModalScreen
from textual.widgets import DataTable, Footer, Markdown, Select, Static
from textual.worker import get_current_worker
+from .host import HostSample, HostSampler
from .collector import BACKEND, Collector, ProcRow, Snapshot, enumerate_adapters, ordered_adapters
from .llm import gb
from .nvml import NvDevice, format_metric
@@ -174,6 +175,7 @@ class GpuTaskManager(App):
CSS = """
Screen { layout: vertical; }
#dashboard { height: auto; max-height: 50%; }
+ #system { height: auto; border: round $success; padding: 0 1; }
#device { height: auto; border: round $accent; padding: 0 1; }
#history { height: auto; border: round $secondary; padding: 0 1; }
#chart-controls { height: 1; }
@@ -196,6 +198,7 @@ class GpuTaskManager(App):
Binding("question_mark", "help", "Explain"),
]
SORTS = [("VRAM", lambda r: -(r.gpu.shown_vram or 0)), ("GPU%", lambda r: -r.gpu.gpu_pct),
+ ("RAM", lambda r: -(r.ram or 0)), ("CPU%", lambda r: -(r.cpu or 0)),
("spill", lambda r: -r.gpu.shared), ("paged", lambda r: -r.gpu.paged_out),
("name", lambda r: r.name.lower())]
CHART_COLORS = {
@@ -210,8 +213,13 @@ class GpuTaskManager(App):
}
CHARTS = tuple(CHART_COLORS)
- def __init__(self, gpu_index: int | None = None, interval: float = 1.0, host: bool = True) -> None:
+ def __init__(self, gpu_index: int | None = None, interval: float = 1.0, host: bool = True,
+ system: bool = True) -> None:
super().__init__()
+ self.system = system
+ self.host_sample: HostSample | None = None
+ self.hist_cpu: deque = deque(maxlen=60)
+ self.hist_ram: deque = deque(maxlen=60)
self.gpu_index = gpu_index
self.interval = interval
self.host = host
@@ -248,6 +256,8 @@ class GpuTaskManager(App):
def compose(self) -> ComposeResult:
with VerticalScroll(id="dashboard"):
+ if self.system:
+ yield Static("Sampling RAM and CPU...", id="system")
yield Static("Sampling GPU counters...", id="device")
with Vertical(id="history"):
with Horizontal(id="chart-controls"):
@@ -266,7 +276,10 @@ class GpuTaskManager(App):
def on_mount(self) -> None:
t = self.query_one("#procs", DataTable)
- for col in ("PID", "Process", "Kind", "Runtime", "VRAM", "Spill", "Paged", "GPU%", "3D", "Copy", "Video", "What's inside"):
+ cols = ["PID", "Process", "Kind", "Runtime", "VRAM", "Spill", "Paged", "GPU%", "3D", "Copy", "Video"]
+ if self.system:
+ cols += ["RAM", "CPU%"]
+ for col in (*cols, "What's inside"):
t.add_column(col, key=col)
t.focus()
self.poll()
@@ -285,12 +298,14 @@ class GpuTaskManager(App):
collector.host_status = "off (multi-GPU WSL host matching is not validated; use --gpu N)"
stack.callback(collector.close)
collectors.append(collector)
+ hs = HostSampler() if self.system else None
worker.cancelled_event.wait(0.5)
while not worker.is_cancelled:
if not self.paused:
snapshots = [collector.sample() for collector in collectors]
+ host = hs.sample() if hs else None
if not worker.is_cancelled:
- self.call_from_thread(self.apply_all, snapshots)
+ self.call_from_thread(self.apply_all, snapshots, host)
worker.cancelled_event.wait(self.interval)
# ------------------------------------------------------------------ rendering
@@ -298,10 +313,18 @@ class GpuTaskManager(App):
def apply(self, snap: Snapshot) -> None:
self.apply_all([snap])
- def apply_all(self, snapshots: list[Snapshot]) -> None:
+ def apply_all(self, snapshots: list[Snapshot], host: HostSample | None = None) -> None:
if not self.is_running:
return # A worker may finish sampling after shutdown has removed the widgets.
self.snapshots = snapshots
+ if host is not None:
+ self.host_sample = host
+ self.hist_cpu.append(host.cpu_pct)
+ self.hist_ram.append(100 * host.ram_used / host.ram_total if host.ram_total else None)
+ for snap in snapshots:
+ for row in snap.procs: # Windows (W:) / outside (H:) rows have no local pid: RAM/CPU stay unknown
+ hp = self.host_sample.proc(row.pid) if self.host_sample and not row.host else None
+ row.ram, row.cpu = (hp.rss, hp.cpu_pct) if hp else (None, None)
multi = len(snapshots) > 1
table = self.query_one("#procs", DataTable)
if multi and "GPU" not in table.columns:
@@ -370,12 +393,49 @@ class GpuTaskManager(App):
if len(self.snapshots) > 1:
devices.append(Text(f"GPU {index}", style="bold"))
devices.append(self.render_device(snap))
+ if self.system and self.host_sample:
+ self.query_one("#system", Static).update(self.render_system(self.host_sample))
device = self.query_one("#device", Static)
device.border_title = "Slim monitoring" if self.monitoring else "Full diagnostics"
device.update(
Group(*devices) if len(self.snapshots) > 1 else devices[0])
self.render_charts()
+ def render_system(self, h: HostSample) -> Group:
+ """System RAM + CPU (fork addition). All values are OS-reported via psutil / NtQuerySystemInformation."""
+ width = max(min(self.size.width - 50, 80), 16)
+ ram_pct = 100 * h.ram_used / h.ram_total if h.ram_total else 0
+ ram = Text("RAM ")
+ ram.append_text(stacked_bar([(h.ram_used, "dodger_blue2")], h.ram_total, width))
+ ram.append(f" {gb(h.ram_used)} / {gb(h.ram_total)}", style="bold")
+ ram.append(f" {ram_pct:.0f}% free {gb(h.ram_available)}", style="grey62")
+ if h.swap_total:
+ ram.append(f" pagefile {gb(h.swap_used)}/{gb(h.swap_total)}",
+ style="yellow" if h.swap_used > h.swap_total / 4 else "grey62")
+ cpu = Text("CPU ")
+ cpu.append_text(stacked_bar([(h.cpu_pct, "green3")], 100, width))
+ cpu.append(f" {h.cpu_pct:4.0f}%", style="bold")
+ cpu.append(f" {h.logical} threads" + (f"/{h.physical} cores" if h.physical else "")
+ + (f" {h.cpu_mhz:.0f} MHz" if h.cpu_mhz else ""), style="grey62")
+ cores = Text(" ")
+ for v in h.per_core:
+ cores.append(SPARK[min(int(v / 100 * (len(SPARK) - 1) + 0.5), len(SPARK) - 1)],
+ style="red" if v >= 90 else "yellow" if v >= 60 else "green3")
+ cores.append(" per-thread", style="grey50")
+ hist = Text(" ")
+ hist.append(spark(self.hist_cpu, 30), style="green3")
+ hist.append(" CPU 60s ", style="grey50")
+ hist.append(spark(self.hist_ram, 30), style="dodger_blue2")
+ hist.append(" RAM 60s", style="grey50")
+ lines = [ram, cpu, cores, hist]
+ if not self.monitoring:
+ top = Text(" top RAM: ", style="grey62")
+ top.append(" ".join(f"{p.name} {gb(p.rss)}" for p in h.top("rss", 5)))
+ top.append("\n top CPU: ", style="grey62")
+ top.append(" ".join(f"{p.name} {p.cpu_pct:.0f}%" for p in h.top("cpu_pct", 5) if p.cpu_pct >= 0.5) or "idle")
+ lines.append(top)
+ return Group(*lines)
+
def render_device(self, s: Snapshot) -> Group:
nv = s.nv
name = s.adapter.name if s.adapter else (nv.name if nv else "GPU")
@@ -600,6 +660,10 @@ class GpuTaskManager(App):
pct(e.get("3d", 0) + e.get("compute", 0) if split else None),
pct(e.get("copy", 0) if split else None),
pct(e.get("decode", 0) + e.get("encode", 0) + e.get("video", 0) if split else None),
+ *([Text(gb(r.ram) if r.ram is not None else "n/a", justify="right",
+ style="" if r.ram is not None else "grey62"),
+ pct(r.cpu) if r.cpu is not None or r.host else Text("…", justify="right", style="grey62")]
+ if self.system else []),
Text(r.inside, style="magenta" if r.llm else "grey62", overflow="ellipsis", no_wrap=True),
*([Text("?" if s.backend == "wsl" and not r.host else str(r.gpu_index))]
if len(self.snapshots) > 1 else []),
diff --git a/src/gputaskman/cli.py b/src/gputaskman/cli.py
index 8ef2cea..7b801a3 100644
--- a/src/gputaskman/cli.py
+++ b/src/gputaskman/cli.py
@@ -38,6 +38,7 @@ def main() -> None:
ap.add_argument("--list-gpus", action="store_true", help="list selectable GPU adapters and exit")
ap.add_argument("--no-host", action="store_true",
help="WSL: don't read Windows host GPU counters through interop (WSL VM total, Windows apps)")
+ ap.add_argument("--no-system", action="store_true", help="hide the system RAM/CPU panel and columns")
ap.add_argument("-i", "--interval", type=float, default=1.0, help="refresh seconds (default 1)")
args = ap.parse_args()
if args.gpu is not None and args.gpu < 0:
@@ -65,6 +66,7 @@ def main() -> None:
if args.once or args.json:
from .collector import Collector
+ from .host import HostSampler
from .report import dump
try:
@@ -76,12 +78,15 @@ def main() -> None:
c.host.wait(15.0) # WSL: the first Windows counter sample takes several seconds
if hasattr(c.counters, "warm_up"):
c.counters.warm_up(15.0) # macOS: per-process GPU memory comes from a background footprint pass
+ hs = None if args.no_system else HostSampler()
+ if hs:
+ hs.sample() # CPU% is a rate too; this primes it
time.sleep(1.0) # engine utilization is a rate; needs two samples
- print(dump(c.sample(), args.json))
+ print(dump(c.sample(), args.json, hs.sample() if hs else None))
finally:
c.close()
return
from .app import GpuTaskManager
- GpuTaskManager(gpu_index=args.gpu, interval=args.interval, host=not args.no_host).run()
+ GpuTaskManager(gpu_index=args.gpu, interval=args.interval, host=not args.no_host, system=not args.no_system).run()
diff --git a/src/gputaskman/collector.py b/src/gputaskman/collector.py
index 9d3cd63..f8f07c0 100644
--- a/src/gputaskman/collector.py
+++ b/src/gputaskman/collector.py
@@ -52,6 +52,8 @@ class ProcRow:
host: bool = False # pid is from another PID namespace, never a local one (see origin)
origin: str = "" # with host: "windows" (a Windows process seen from WSL) | "outside" (outside this container)
gpu_index: int | None = None
+ ram: int | None = None # system RAM (working set) from host.py; None = unknown, not zero
+ cpu: float | None = None # % of the whole machine from host.py; None until the second sample
@property
def key(self) -> str:
diff --git a/src/gputaskman/host.py b/src/gputaskman/host.py
new file mode 100644
index 0000000..ffeaff8
--- /dev/null
+++ b/src/gputaskman/host.py
@@ -0,0 +1,202 @@
+"""System RAM and CPU, alongside the GPU view.
+
+Every number here is reported by the OS through psutil (measured, not inferred). Unknown stays None:
+a process we may not inspect has ``rss=None`` / ``cpu_pct=None``, never 0. Fork addition, not upstream.
+"""
+
+from __future__ import annotations
+
+import struct
+import sys
+import time
+from dataclasses import dataclass, field
+
+import psutil
+
+
+@dataclass
+class HostProc:
+ pid: int
+ name: str
+ rss: int | None # resident / working set bytes
+ private: int | None # Windows private bytes (commit charged to the process); None elsewhere
+ cpu_pct: float | None # share of the WHOLE machine (0-100), like Task Manager; None on the first sample
+
+
+@dataclass
+class HostSample:
+ cpu_pct: float # whole machine, 0-100
+ per_core: list[float]
+ cpu_mhz: float | None
+ logical: int
+ physical: int | None
+ ram_total: int
+ ram_used: int # total - available (what Task Manager calls "In use", approximately)
+ ram_available: int
+ swap_total: int
+ swap_used: int
+ procs: list[HostProc] = field(default_factory=list)
+ denied: int = 0 # processes whose memory we were not allowed to read
+ cost_ms: float = 0.0
+
+ def proc(self, pid: int | None) -> HostProc | None:
+ return self._by_pid.get(pid) if pid is not None else None
+
+ def __post_init__(self) -> None:
+ self._by_pid = {p.pid: p for p in self.procs}
+
+ def top(self, key: str, n: int = 5) -> list[HostProc]:
+ return sorted((p for p in self.procs if getattr(p, key) is not None), key=lambda p: -getattr(p, key))[:n]
+
+
+class HostSampler:
+ """Keeps psutil.Process objects between samples: per-process CPU% is a rate and needs the previous reading."""
+
+ def __init__(self) -> None:
+ self._procs: dict[int, psutil.Process] = {}
+ self._rated: set[int] = set() # pids with a previous CPU reading
+ self._logical = psutil.cpu_count() or 1
+ self._physical = psutil.cpu_count(logical=False)
+ self._last_cpu: dict[int, int] = {}
+ self._last_wall = 0.0
+ psutil.cpu_percent(percpu=True) # prime the system-wide rate
+
+ def sample(self) -> HostSample:
+ t0 = time.perf_counter()
+ per_core = psutil.cpu_percent(percpu=True)
+ vm, sw = psutil.virtual_memory(), psutil.swap_memory()
+ try:
+ freq = psutil.cpu_freq()
+ mhz = freq.current if freq and freq.current else None
+ except (OSError, NotImplementedError): # unavailable on some platforms/containers
+ mhz = None
+ if _nt_query is not None:
+ procs, denied = self._sample_nt(), 0
+ return self._finish(t0, per_core, mhz, vm, sw, procs, denied)
+ procs, denied, seen = [], 0, set()
+ for p in psutil.process_iter():
+ pid = p.pid
+ seen.add(pid)
+ p = self._procs.setdefault(pid, p)
+ try:
+ with p.oneshot():
+ name = p.name()
+ mi = p.memory_info()
+ cpu = p.cpu_percent(None)
+ except psutil.NoSuchProcess:
+ continue
+ except psutil.AccessDenied:
+ denied += 1
+ procs.append(HostProc(pid, _safe_name(p), None, None, None))
+ continue
+ first = pid not in self._rated
+ self._rated.add(pid)
+ procs.append(HostProc(pid, name, mi.rss, getattr(mi, "private", None),
+ None if first else cpu / self._logical))
+ for gone in self._procs.keys() - seen:
+ del self._procs[gone]
+ self._rated &= seen
+ return self._finish(t0, per_core, mhz, vm, sw, procs, denied)
+
+ def _sample_nt(self) -> list[HostProc]:
+ now = time.perf_counter()
+ rows = _nt_query()
+ wall = now - self._last_wall if self._last_wall else None
+ procs = []
+ for pid, (name, ws, private, cpu100ns) in rows.items():
+ prev = self._last_cpu.get(pid)
+ cpu = None
+ if wall and prev is not None and pid != 0: # pid 0 = System Idle Process: its "CPU" is idle time
+ cpu = max(0.0, (cpu100ns - prev) / 1e7 / wall / self._logical * 100)
+ procs.append(HostProc(pid, name, ws, private, cpu))
+ self._last_cpu = {pid: r[3] for pid, r in rows.items()}
+ self._last_wall = now
+ return [p for p in procs if p.pid != 0]
+
+ def _finish(self, t0, per_core, mhz, vm, sw, procs, denied) -> HostSample:
+ return HostSample(
+ cpu_pct=sum(per_core) / len(per_core) if per_core else 0.0, per_core=per_core, cpu_mhz=mhz,
+ logical=self._logical, physical=self._physical,
+ ram_total=vm.total, ram_used=vm.total - vm.available, ram_available=vm.available,
+ swap_total=sw.total, swap_used=sw.used, procs=procs, denied=denied,
+ cost_ms=(time.perf_counter() - t0) * 1000)
+
+
+# Windows: one NtQuerySystemInformation(SystemProcessInformation) call returns every process's working set,
+# private bytes and CPU time. psutil opens each process instead: measured 2026-11-08 on a 483-process
+# Windows 11 box, memory_info ~1.1 s and cpu_times ~1.0 s per pass, versus a few ms here. Same numbers:
+# WorkingSetSize = psutil rss, PagefileUsage = psutil private. No process handle needed, so no AccessDenied.
+_nt_query = None
+if sys.platform == "win32" and struct.calcsize("P") == 8:
+ import ctypes
+
+ _ntdll = ctypes.WinDLL("ntdll")
+ _ntdll.NtQuerySystemInformation.restype = ctypes.c_long
+
+ def _nt_query_impl() -> dict[int, tuple[str, int, int, int]]:
+ size = 1 << 20
+ while True:
+ buf = ctypes.create_string_buffer(size)
+ need = ctypes.c_ulong()
+ status = _ntdll.NtQuerySystemInformation(5, buf, size, ctypes.byref(need)) # SystemProcessInformation
+ if status == -1073741820: # STATUS_INFO_LENGTH_MISMATCH: processes appeared; grow and retry
+ size = max(size * 2, need.value + (64 << 10))
+ continue
+ if status < 0:
+ raise OSError(f"NtQuerySystemInformation failed: 0x{status & 0xffffffff:08x}")
+ break
+ raw, base, out, off = buf.raw, ctypes.addressof(buf), {}, 0
+ while True:
+ nxt = struct.unpack_from("<I", raw, off)[0]
+ user, kernel = struct.unpack_from("<qq", raw, off + 40)
+ name_len, name_ptr = struct.unpack_from("<H6xQ", raw, off + 56)
+ pid = struct.unpack_from("<Q", raw, off + 80)[0]
+ ws, = struct.unpack_from("<Q", raw, off + 144)
+ private, = struct.unpack_from("<Q", raw, off + 184)
+ if name_ptr:
+ name = raw[name_ptr - base:name_ptr - base + name_len].decode("utf-16-le", "replace")
+ else:
+ name = "System Idle Process" if pid == 0 else "?"
+ out[pid] = (name, ws, private, user + kernel)
+ if not nxt:
+ return out
+ off += nxt
+
+ _nt_query = _nt_query_impl
+
+
+def _safe_name(p: psutil.Process) -> str:
+ try:
+ return p.name()
+ except psutil.Error:
+ return "?"
+
+
+def to_dict(h: HostSample) -> dict:
+ return {
+ "source": "psutil (OS-reported)",
+ "cpu": {"pct": round(h.cpu_pct, 1), "per_core": h.per_core, "mhz": h.cpu_mhz,
+ "logical": h.logical, "physical": h.physical},
+ "ram": {"total": h.ram_total, "used": h.ram_used, "available": h.ram_available,
+ "swap_total": h.swap_total, "swap_used": h.swap_used},
+ "top_ram": [vars(p) for p in h.top("rss", 10)],
+ "top_cpu": [vars(p) for p in h.top("cpu_pct", 10)],
+ "denied": h.denied,
+ "cost_ms": round(h.cost_ms, 1),
+ }
+
+
+def to_text(h: HostSample) -> str:
+ from .llm import gb
+
+ lines = [f"CPU {h.cpu_pct:.0f}% {h.logical} threads" + (f" / {h.physical} cores" if h.physical else "")
+ + (f" {h.cpu_mhz:.0f} MHz" if h.cpu_mhz else ""),
+ f"RAM {gb(h.ram_used)} / {gb(h.ram_total)} available {gb(h.ram_available)}"
+ f" swap/pagefile {gb(h.swap_used)} / {gb(h.swap_total)}",
+ "", f"{'PID':>7} {'PROCESS':<28} {'RAM':>9} {'PRIVATE':>9} {'CPU%':>5}"]
+ for p in h.top("rss", 10):
+ lines.append(f"{p.pid:>7} {p.name[:28]:<28} {gb(p.rss):>9} {gb(p.private) if p.private is not None else 'n/a':>9} "
+ f"{f'{p.cpu_pct:.0f}' if p.cpu_pct is not None else 'n/a':>5}")
+ if h.denied:
+ lines.append(f"({h.denied} processes not readable without admin)")
+ return "\n".join(lines)
diff --git a/src/gputaskman/report.py b/src/gputaskman/report.py
index f0f0062..08cc2ff 100644
--- a/src/gputaskman/report.py
+++ b/src/gputaskman/report.py
@@ -250,5 +250,13 @@ def to_text(s: Snapshot, limit: int = 30) -> str:
return "\n".join(out)
-def dump(s: Snapshot, as_json: bool) -> str:
- return json.dumps(to_dict(s), indent=2, default=str) if as_json else to_text(s)
+def dump(s: Snapshot, as_json: bool, host=None) -> str:
+ """host: an optional host.HostSample (system RAM/CPU), added as a "host" section."""
+ from . import host as hostmod
+
+ if as_json:
+ d = to_dict(s)
+ if host is not None:
+ d["host"] = hostmod.to_dict(host)
+ return json.dumps(d, indent=2, default=str)
+ return to_text(s) + ("\n\n" + hostmod.to_text(host) if host is not None else "")
diff --git a/tests/test_host.py b/tests/test_host.py
new file mode 100644
index 0000000..a18053e
--- /dev/null
+++ b/tests/test_host.py
@@ -0,0 +1,40 @@
+import os
+import sys
+import unittest
+
+import psutil
+
+from gputaskman import host
+
+
+class HostTests(unittest.TestCase):
+ def test_unknown_is_not_zero(self):
+ h = host.HostSample(cpu_pct=5, per_core=[5], cpu_mhz=None, logical=1, physical=1, ram_total=100,
+ ram_used=40, ram_available=60, swap_total=0, swap_used=0,
+ procs=[host.HostProc(1, "a", None, None, None), host.HostProc(2, "b", 10, 5, 0.0)])
+ self.assertEqual([p.pid for p in h.top("rss")], [2]) # the unreadable process is not ranked as 0
+ self.assertIsNone(h.proc(1).rss)
+ self.assertIsNone(host.to_dict(h)["cpu"]["mhz"])
+
+ @unittest.skipUnless(sys.platform == "win32", "NtQuerySystemInformation is Windows-only")
+ def test_nt_query_matches_psutil(self):
+ me = psutil.Process(os.getpid())
+ name, ws, private, cpu = host._nt_query()[os.getpid()]
+ mi = me.memory_info()
+ self.assertEqual(name.lower(), me.name().lower())
+ self.assertLess(abs(private - mi.private), 8 << 20)
+ self.assertLess(abs(ws - mi.rss), 16 << 20)
+ self.assertGreater(cpu, 0)
+
+ def test_sampler_rates_cpu_after_second_sample(self):
+ s = host.HostSampler()
+ first = s.sample()
+ self.assertTrue(all(p.cpu_pct is None for p in first.procs)) # a rate needs two readings
+ second = s.sample()
+ self.assertTrue(any(p.cpu_pct is not None for p in second.procs))
+ self.assertTrue(0 <= second.cpu_pct <= 100)
+ self.assertGreater(second.ram_total, second.ram_used > 0)
+
+
+if __name__ == "__main__":
+ unittest.main()