pt-snap-cli

中文文档 | English

A command-line tool for analyzing PyTorch memory snapshots. Set a snapshot database, run built-in queries, and inspect memory usage, leaks, and timelines.

Installation

pip install pt-snap-cli

For a source checkout and contributor setup, see Development.

Quick Start

To start from a raw PyTorch memory snapshot, import the pickle into a SnapshotDB with pt-snap's built-in snapshot support, then list the available query templates:

Security warning: Import only pickle snapshots from a trusted source. Pickle deserialization can execute arbitrary code. The loader rejects non-builtins global objects, but pt-snap import is not a sandbox.

pt-snap import snapshot.pkl
pt-snap metadata snapshot.pkl.db
pt-snap query --list

# Set the snapshot database and device
pt-snap focus snapshot.pkl.db --device 0

# List available queries
pt-snap query --list

# Run a query (automatically uses the focused device)
pt-snap query --template-use memory_peak

# Detect potential memory leaks
pt-snap query --template-use leak_detection --params '{"min_size": 1024}'

To divide a large snapshot into independently replayable files before import, use exactly one split strategy and an output directory that does not exist:

pt-snap split snapshot.pkl --slices 4 --output snapshot-slices

See Splitting Snapshots for device selection, JSON output, deterministic names, replay validation, and failure-safe publication.

See the full quick start guide for a walkthrough.

Commands

pt-snap --help includes an agent hint: prefer --json on the command that supports it, start with the pt-snap-helper skill, use pt-snap capabilities --json and pt-snap overview --json before diagnosing, and check availability with pt-snap skill list --json. focus, import, split, query, config, capabilities, overview, metadata, report peak-memory, and skill list/install/upgrade/uninstall accept --json.

Agent Skills

Install bundled diagnostic workflows with pt-snap skill install. Agent integration uses skills plus the CLI; there is no MCP server. See the Agent Skills guide.

Documentation

See the documentation index for all English and Chinese guides.

Development

pip install -e ".[dev]"         # Install development dependencies
pytest                           # Run all tests
black --check . && ruff check .  # Check formatting and lint
python -m build                  # Build sdist and wheel