How to Use the spindump Command in macOS Terminal to Diagnose Unresponsive Apps and Hangs

When an application locks up on macOS and triggers the spinning wait cursor (commonly known as the “beachball”), standard activity monitors only reveal high CPU or RAM consumption. They cannot pinpoint which thread, kernel lock, or blocked I/O call caused the freeze. In macOS, Apple provides spindump, a low-level diagnostic utility that samples thread instruction pointers across user space and the XNU kernel without suspending or terminating the active process. Understanding how to execute and interpret spindump enables system administrators, developers, and advanced users to troubleshoot software bottlenecks with surgical precision.

How spindump Samples Process Hangs

Unlike invasive debuggers like LLDB that halt program execution to inspect memory, spindump operates non-destructively:

• Stack Sampling: spindump periodically inspects the call stack of every active thread within a specified process or across the entire operating system (typically sampling at 10ms intervals over a 10-second window).
• Hang Detection: By comparing call stacks over time, spindump identifies “heavy” execution paths—threads stuck repeatedly in the same function or waiting indefinitely for lock acquisitions and system calls.
• Symbol Resolution: On macOS, spindump automatically maps raw memory addresses to human-readable framework symbols using dSYM symbolication and system dynamic linker caches.
• Output Generation: Produces detailed text-based diagnostic files formatted for manual terminal inspection or viewing in Console.app.

Basic Syntax and Terminal Execution

Because spindump inspects low-level kernel data structures and process threads, execution requires superuser (sudo) privileges:

sudo spindump [PID or ProcessName] [duration_in_seconds] [interval_in_ms] -file [output_path]

If executed without specifying a target process or PID, spindump captures a global system-wide thread profile:

sudo spindump -file ~/Desktop/system_spindump.txt

Targeting a Specific Unresponsive Application

To profile a specific hung application without capturing unrelated background services:

1. Open Terminal on your Mac.
2. Find the Process ID (PID) of the hanging app using pgrep:

   pgrep -x "Safari"

3. Run spindump targeting the specific PID for a 10-second duration:

   sudo spindump 2841 10 -file ~/Desktop/safari_hang.txt

4. Terminal will display a real-time progress indicator: Sampling process 2841 for 10 seconds with 10 milliseconds of run time between samples…
5. Once complete, spindump writes the symbolic call trace to the designated output file.

Common spindump Command-Line Options

You can fine-tune spindump output to suppress noise or capture lightweight traces:

Flag / Option	Description	Example Usage
-onlybusy	Samples only threads that are actively executing code or consuming CPU time, ignoring idle waiting threads.	sudo spindump -onlybusy -file busy_threads.txt
-timeline	Generates a chronological timeline view of thread state transitions rather than an aggregated tree.	sudo spindump Safari -timeline -file timeline.txt
-heavy	Sorts the call tree by heaviest execution paths first, placing the most active stack traces at the top of the report.	sudo spindump -heavy -file heavy_stacks.txt
-no-kernel	Omits kernel-level thread call stacks to produce cleaner user-space reports for app developers.	sudo spindump Xcode -no-kernel -file xcode_user.txt

Reading and Interpreting a spindump Report

Open the generated report in your preferred text editor (or via less in Terminal). A spindump file is divided into several structured sections:

1. Header Metadata: Details macOS build version, hardware model, thermal state, and total sample duration.
2. Process Summary: Displays CPU percentage, memory footprint, architecture (ARM64 or x86_64), and code signing status.
3. Thread Trees: Each thread is numbered. Look for threads marked with (Thread 0x1a2b, Thread name: Main Thread, 1000 samples).
4. Stack Trace Symbols: Follow the indented call hierarchy from top to bottom. If all 1,000 samples are concentrated inside a specific function—such as a database query, file lock, or network socket write—that specific line reveals the root cause of the beachball.