Apple Silicon · GPU · CPU · unified memory

gpucap

Run any command like time(1) and report GPU, CPU, and unified memory utilization on Apple Silicon Macs. Colorized human reports on TTY; -f format strings for scripts — with BrightDate timestamps for log correlation.

# wrap a command — colored report on stderr $ gpucap ffmpeg -i in.mp4 out.mp4 gpu avg 12.3% peak 45.6% cpu avg 8.1% peak 23.4% memory avg 52.0% peak 55.1% real 1.234567 s # machine output — CSV with BrightDate start/end $ gpucap -f '%gA,%gP,%uA,%uP,%hA,%hP,%e,%Ws,%Wt' sleep 1 0.0,0.0,2.1,4.3,51.2,51.4,1.00,9628.198441000,9628.199441000
Install → Format spec crates.io GitHub
Usage

Wrap any command.

gpucap forks and execs your command, polls metrics every 100 ms (configurable with --interval), then prints a summary to stderr. Exit status matches the child process. 

gpucap sleep 1
gpucap --color=bright -- ffmpeg -i in.mp4 out.mp4
gpucap --interval 50 make -j8

GPU exerciser

gpuexercise is a subcommand (not a separate binary) that drives sustained GPU load via a Metal compute shader and feedback loop: 

gpucap gpuexercise --percent 50 --seconds 10
gpucap gpuexercise -f 'target=%tG gpu=%gA/%gP elapsed=%e' -p 75 -s 5

Requirements

macOS on Apple Silicon (M1/M2/M3/M4+), arm64 only. Reads AGX GPU metrics and unified memory statistics unavailable on Intel Macs or non-macOS platforms.

Color output

--color[=WHEN] — auto, always, never, plain, ansi, truecolor. --color-scheme — default or bright. Env: GPUCAP_COLOR, GPUCAP_COLOR_SCHEME, plus NO_COLOR / CLICOLOR.

Format vs. color: When -f / --format (or GPUCAP_FORMAT) is set, output is always plain text — even if --color=always. This matches BrightDate ecosystem conventions: human reports colorize on TTY; machine format strings stay script-safe.

Machine output

-f / --format

Custom format strings follow BrightDate FORMAT-SPEC where applicable, plus gpucap-specific utilization specifiers. Set via -f or environment variable GPUCAP_FORMAT. 

gpucap -f '%gA,%gP,%uA,%uP,%hA,%hP,%e,%Ws,%Wt' sleep 1
gpucap -f 'cmd=%C x=%x gpu_peak=%gP start=%Ws' cargo build
gpucap

Utilization specifiers

All percentages output one decimal place, no % suffix.

Specifier Meaning
%gA / %gPGPU average / peak %
%uA / %uPCPU average / peak % (system-wide)
%hA / %hPUnified memory average / peak %
%tGExercise target GPU % (gpuexercise only)
BrightDate

Timing & timestamps

Shared with btime -f — see FORMAT-SPEC tiers A–C.

Specifier Meaning Output
%Ws / %NCommand start wall time{:.9} BrightDate days
%Wt / %nCommand end wall time{:.9} BrightDate days
%eElapsed secondssec.centis (GNU style)
%EElapsed wall timem:ss.cc or h:mm:ss
%BElapsed wall time{:.9} BrightDate days
%bElapsed millidays{:.6} (no suffix)
%dEElapsed millidays{:.6} md
%CCommand lineargv joined with spaces
%xExit statuschild exit code
%%Literal %
\t, \nTab / newline

Default machine format: %gA,%gP,%uA,%uP,%hA,%hP,%e,%Ws,%Wt\n

Data sources

What gets measured.

Metric Source Notes
GPU IOKit Device Utilization % IOReport fallback when IOKit unavailable
CPU Mach host_processor_info System-wide, not per-process
Memory host_statistics64 + hw.memsize Unified RAM on Apple Silicon

Samples are taken every --interval ms (default 100) while the child runs. Average and peak are computed over all samples.

Getting started

Install.

1

Cargo

cargo install gpucap
gpucap sleep 1
2

Homebrew

brew tap digital-defiance/tap
brew install digital-defiance/tap/gpucap
3

Verify

gpucap --version
gpucap --help
gpucap -f '%gA,%uA,%e' sleep 0.1