# Macos Memory > macOS native memory analysis tools (leaks, heap, vmmap, Instruments). Use for native app memory debugging. Use when this capability is needed. - Skill: `tomevault-io/macos-memory` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/macos-memory` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/macos-memory/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/macos-memory --- # macOS Memory Analysis Skill Comprehensive guide for analyzing memory usage and detecting leaks in native macOS applications using Apple's native profiling tools. ## 1. leaks - Memory Leak Detection The `leaks` tool detects unreachable memory allocations that have been leaked. ### Basic Usage ```bash leaks ``` Check a running process for memory leaks: ```bash leaks 1234 ``` ### Run App and Check at Exit Run an application and automatically check for leaks when it exits: ```bash leaks --atExit -- ./myapp leaks --atExit -- /path/to/binary arg1 arg2 ``` ### Common Options - `leaks ` - Check running process - `leaks --atExit -- ` - Check application at exit - `leaks --nocontext` - Suppress stack trace context - `leaks --nostacks` - Don't print stack traces (faster) ### Example Output The tool will report: - Number of leaked memory blocks - Total leaked memory size - Stack traces showing where leaks originated ## 2. heap - Heap Analysis The `heap` tool provides detailed information about heap memory allocations. ### Basic Usage ```bash heap ``` Show heap summary: ```bash heap 1234 ``` ### Show All Allocations ```bash heap -addresses all ``` Dump all allocation addresses (detailed, slow for large heaps): ```bash heap 1234 -addresses all ``` ### Common Options - `heap ` - Show heap summary - `heap -addresses all` - Show all individual allocations - `heap -addresses ` - Show allocations above a certain size - `heap -diffFrom ` - Compare heap to a previous snapshot ### Interpretation - **Zone** - Memory zone information - **Count** - Number of allocations - **Total** - Total allocated bytes - **Avg** - Average allocation size - **Max** - Largest single allocation ## 3. vmmap - Virtual Memory Map The `vmmap` tool shows the complete virtual memory map of a process, including all memory regions and their usage. ### Basic Usage ```bash vmmap ``` Show full virtual memory map: ```bash vmmap 1234 ``` ### Filter for Malloc Regions ```bash vmmap | grep MALLOC ``` ### Memory Region Types Common memory region types in output: - **MALLOC** - Memory allocated by malloc - **STACK** - Thread stacks - **TEXT** - Code/executable sections - **DATA** - Static data - **PAGEZERO** - Zero page (guard region) - **OBJC** - Objective-C runtime - **CF** - CoreFoundation ### Example Analysis ```bash vmmap 1234 | grep -E "MALLOC|TOTAL" ``` Shows only malloc regions and totals for quick overview. ## 4. Instruments CLI - Advanced Profiling The `xcrun instruments` command-line tool provides professional profiling capabilities. ### Leaks Instrument Detect memory leaks while capturing detailed information: ```bash xcrun instruments -t "Leaks" ./myapp xcrun instruments -t "Leaks" -l 30000 ./myapp ``` ### Allocations Instrument Track all memory allocations: ```bash xcrun instruments -t "Allocations" ./myapp xcrun instruments -t "Allocations" -l 30000 ./myapp ``` ### Common Options - `-t "Name"` - Instrument template to use - `-l ` - Recording duration in milliseconds - `-o ` - Output file path (.trace format) - `-s ` - Start delay in milliseconds - `-p ` - Attach to running process ### Available Instruments Common instruments for memory analysis: - **Leaks** - Memory leak detection - **Allocations** - Memory allocation tracking - **VM Tracker** - Virtual memory analysis - **System Trace** - Low-level system events ### Saving Results ```bash xcrun instruments -t "Leaks" -o /tmp/myapp.trace ./myapp ``` Results can be opened in Instruments.app for GUI analysis. ## 5. Finding Process ID (PID) ### Using pgrep Find process by partial name match: ```bash pgrep -f kattle pgrep -f "kattle.*--flag" ``` Get first matching PID: ```bash pgrep -f kattle | head -1 ``` ### Using ps Alternative method with ps: ```bash ps aux | grep kattle ps aux | grep -i "MyApp" ``` Extract PID from ps output: ```bash ps aux | grep kattle | grep -v grep | awk '{print $2}' ``` ### Using Activity Monitor CLI ```bash open -a Activity\ Monitor ``` ## Workflow Examples ### Quick Memory Check ```bash PID=$(pgrep -f kattle | head -1) echo "Process: kattle (PID: $PID)" ps -o rss= -p $PID | awk '{printf "RSS: %.2f MB\n", $1/1024}' ``` ### Comprehensive Leak Detection ```bash PID=$(pgrep -f myapp | head -1) echo "=== Leak Detection ===" leaks $PID echo "=== Heap Summary ===" heap $PID echo "=== Top Malloc Regions ===" vmmap $PID | grep -i malloc | head -10 ``` ### Profile Until Problem Occurs ```bash # Start profiling with Leaks instrument xcrun instruments -t "Leaks" -o /tmp/profile.trace ./myapp # Open results in Instruments.app open /tmp/profile.trace ``` ### Memory Growth Analysis ```bash PID=$(pgrep -f myapp | head -1) # Capture initial heap snapshot heap $PID > /tmp/heap_initial.txt # Wait for activity sleep 10 # Compare with second snapshot heap $PID -diffFrom /tmp/heap_initial.txt ``` ## Tips and Best Practices 1. **Run as appropriate user** - May need `sudo` for privileged processes 2. **Stop background activity** - Close other apps to reduce noise 3. **Warm up the app** - Run app briefly to reach stable state 4. **Use vmmap for overview** - Get big picture of memory usage 5. **Use heap for detail** - Drill down into allocation patterns 6. **Use leaks for confirmation** - Verify suspected leaks 7. **Capture baselines** - Take snapshots at known good states 8. **Compare snapshots** - Use diff features to find growth ## Common Issues ### Tool Not Found If tools aren't in PATH, use full paths: ```bash /usr/bin/leaks /usr/bin/heap /usr/bin/vmmap ``` ### Permission Denied Need appropriate privileges for some processes: ```bash sudo leaks sudo xcrun instruments -t "Leaks" ./app ``` ### Instruments Framework Issues Ensure Xcode command line tools are installed: ```bash xcode-select --install ``` ## Related Commands - **sample** - CPU profiling sampler - **dtrace** - Dynamic tracing - **malloc_history** - Track malloc allocations - **memory_statistics** - System-wide memory stats --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/flavono123) — claim your Tome and manage your conversions.