中文文档 | 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.
pip install pt-snap-cliFor a source checkout and contributor setup, see Development.
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-
builtinsglobal objects, butpt-snap importis 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-slicesSee 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.
| 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.
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.
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 |
pip install -e ".[dev]" # Install development dependencies
pytest # Run all tests
black --check . && ruff check . # Check formatting and lintFor 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.
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>.whlReplace <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.