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

MCP Server

pt-snap-cli provides an MCP (Model Context Protocol) server so AI agents can interact with PyTorch memory snapshots programmatically.

# Start the MCP server
pt-snap-mcp

See the MCP guide for setup and usage details.

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