Skip to content

About

PyTorch Memory Snapshot CLI

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

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.

Complete compatibility-v1 sharded artifacts can be focused by directory or manifest.json, without the archived pickle. See dataset focus and addressing for read-only overview, event routing, --slice, and explicit cross-slice limits.

Opt into a native, not msinsight-compatible dataset with pt-snap import snapshot.pkl --events-per-slice 50000 --output-dir captures --json. The output is captures/snapshot.pkl.pt-snap-native-v2/; default standalone import is unchanged. Reuse validates all shards and content/options/semantic versions. Nonmatching recognized targets require --force; unknown targets are preserved. Publication/focus failures are compensated, with explicit recovery evidence if rollback fails (force is not a single crash-atomic swap). See the native import guide. Dataset event addressing and point-event active_blocks_at_event / active_memory_callstack_at_event share batched cross-shard alloc/free sources, including original artifacts without extensions. Built-in global peaks, event pages, canonical stack statistics, deduplicated lifecycles, terminal leak candidates and report peak-memory share bounded core semantics; custom SQL/overrides remain unsupported on datasets. See the global support matrix and dataset attribution and coverage. Lifecycle queries exceeding SQLite's attachment limit use a private, page-limited temporary derived database; source shards stay read-only. See the global support matrix for storage limits, cleanup and memory caveats.

Explicit pt-snap import snapshot.pkl --format msinsight --json produces snapshot.pkl.msinsight/ for the fixed msinsight revision's same original pickle + adjacent cache entrance. Inline stacks cost more space than native interning. Existing compatible targets are never replaced, even with --force; only fully validated identical pt-snap caches are reused. GUI acceptance remains pending/not run; hash equality alone is not acceptance. See compatible export and limits.

See offline interoperability acceptance and bounded performance for the two fixed-version chains, deterministic reference tools, honest three-mode measurements and the explicitly pending/not-run GUI checklist. Diagnostic skills accept explicitly selected complete validated datasets, not arbitrary directories.

Commands

Command Description
pt-snap focus Set and manage analysis focus (database + device)
pt-snap import <snapshot.pkl> Import a PyTorch memory snapshot pickle into a SnapshotDB
pt-snap split <snapshot.pkl> Create replayable per-device snapshot slices
pt-snap metadata [database.db] Inspect SnapshotDB import provenance and compatibility metadata
pt-snap capabilities List CLI version, query template contracts, and bundled skills
pt-snap overview [database.db] Read-only device list, per-device event-id bounds, and import-metadata status
pt-snap query Run memory analysis queries
pt-snap report Generate higher-level memory analysis reports
pt-snap report memory-tree --event-id <id> Frame-level live-memory breakdown; --format html emits an interactive flamegraph
pt-snap config Manage global configuration
pt-snap skill List and install bundled agent skills

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.

Peak reports expose attribution completeness and same-event active-byte coverage; group percentages use included bytes after filtering and ranking. See the report guide before interpreting a capped breakdown.

Standalone imports preserve ordered structured callstack frames. Use event_frames to inspect them, or report memory-tree --event-id 100 --format html > memory-tree.html to explore event-time occupancy by caller path. See frame memory breakdown; older text-only databases require re-importing the original snapshot. report memory-tree also accepts --json. The HTML view has full-tree search and keyboard-accessible child lists, so tiny and zero-byte frames remain reachable.

Dataset work limits are configurable with --max-work-rows, --max-work-bytes, --max-scratch-db-bytes, environment variables, or immutable Python QueryLimits. Defaults remain 100000 work rows / 64 MiB work bytes / 512 MiB scratch pages; see public dataset limits for precedence, deep-pagination costs and all-or-error semantics.

Agent Skills

For long diagnostic stacks, opt into stack_bytes on event or active_memory_callstack_at_event, or report peak-memory --stack-bytes 256. See compact callstack text for identity, byte-budget metadata and full-text retrieval.

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.

Ascend NPU capture can proceed without pt-snap when the host has loaded pt-snap-ascend-npu-collect; the helper routes collection before CLI setup. Analysis still requires the CLI and a SnapshotDB, with trusted import as a separate decision.

Documentation

See the documentation index for all English and Chinese guides.

Topic Guide
Getting started Quick Start
Managing focus Focus Management
Running queries Querying
Splitting snapshots Splitting Snapshots
Agent skills Agent Skills
Database format SnapshotDB Schema
Sharded protocols, native import and compatibility limits Sharded SnapshotDB protocol
Python API SnapshotAnalyzer API
Result mapping utility ResultMapper API

Development

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

For the regular suite use pytest -m 'not slow'. Default-capacity scale and non-editable installed exporter tests are described in the dataset acceptance guide.

The supplemental platform workflow runs Python 3.13 non-slow tests on macOS and Windows. Windows uses four deterministic, disjoint shards of the full non-slow collection; macOS runs it in one job. All five jobs retain a 20-minute limit, with at most two running concurrently. Each Windows shard validates exhaustive coverage before execution and uploads its full collection/partition manifest alongside JUnit results. No tests are skipped to meet the time limit. To reproduce one Windows partition locally, run python .github/scripts/run_platform_tests.py --shard 0 (choose --shard 0 through --shard 3); add --collect-only to inspect the partition without executing tests.

Building distributions

Build from a fresh checkout or a new worktree at the intended commit, with no existing build/ or dist/ directories. Setuptools can reuse files in build/lib on repeated builds, including modules deleted from the source tree; build dependency isolation does not clean these intermediates. Inspect old outputs before removing them yourself, or use a fresh worktree instead.

From that checkout's root:

python -m build                  # Build sdist and wheel
python .github/scripts/audit_wheel.py --wheel dist/<built-wheel>.whl

Replace <built-wheel> with the generated filename. The read-only audit compares Python module paths and bytes with src/, and separately checks query YAML, bundled skills, and snapshot license/provenance resources against the packaging contract. Generated distribution metadata is allowed. A mismatch fails with the affected paths; rebuild from a fresh source tree and audit again before using the wheel. CI audits its wheel before installed-package acceptance; release separately audits the actual wheel it uploads for publication.

About

PyTorch Memory Snapshot CLI

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages