Using gpudebug — Metal GPU Trace Debugger

Overview

gpudebug is a CLI debugger for Metal GPU traces. It opens a .gputrace file and provides commands for navigating the captured API call hierarchy, inspecting resources and pipeline state, fetching textures and buffers to disk, and browsing shader source code.

Step 1: Check availability

which gpudebug

gpudebug ships with macOS 27 and later. If not found, tell the user it is not available and suggest opening the .gputrace in Xcode's Metal Debugger instead: Analyzing your Metal workload

If the user explicitly asks to inspect the trace in Xcode, honor their request — point them to the Apple docs URL above and answer from your own knowledge. Do not override their choice with gpudebug.

Step 2: Read the man page

The man page is the authoritative reference for all commands, options, the trace hierarchy, and node naming conventions. Read it before using gpudebug: