Notebook Snapshots

A VS Code extension that provides comprehensive snapshot management for Jupyter notebooks, enabling experiment versioning, milestone tracking, and instant restoration of previous notebook states.

Overview

Never lose your notebook outputs again. This extension automatically preserves your notebook's complete state including all outputs, visualizations, and data - then lets you browse, view, and restore any previous version with one click.

Key Features

Full Notebook Snapshots

• One-click saving of complete notebook state with all outputs preserved
• Automatic extraction of images and large text outputs to organized files
• Timestamped storage with comprehensive metadata tracking

Selective Cell Snapshots

• Pin important cells for targeted snapshot saving
• Capture only the cells that matter for your current experiment
• Preserve key results without saving entire notebook state

Visual Gallery Browser

• Browse all snapshots through an intuitive web interface
• Thumbnail previews of extracted visualizations and plots
• Rich metadata display including creation time, cell counts, and notes

Instant Notebook Restoration

• Revert your entire notebook to any previous snapshot state
• Safety confirmation to prevent accidental overwrites
• Automatic notebook reload to display restored content

Smart Output Management

• Automatic extraction of PNG/JPEG images from matplotlib, plotly, and other outputs
• Large text outputs (>4KB) saved to separate files for easy access
• Organized file structure with predictable naming conventions

Configurable Retention Policies

• Automatic cleanup based on snapshot count or age limits
• Runs daily and after each snapshot to prevent storage bloat
• Configurable limits to balance storage and history preservation

Installation

From VS Code Marketplace

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "Notebook Snapshots"
4. Click Install

From Source

1. Clone this repository
2. Run npm install to install dependencies
3. Run npm run compile to build the extension
4. Press F5 to launch in Extension Development Host

Usage Guide

Creating Snapshots

Full Notebook Snapshot:

1. Open any Jupyter notebook (.ipynb) in VS Code
2. Click the "Save Full Snapshot" button in the notebook toolbar
3. Optionally add a descriptive note for this snapshot
4. Snapshot saved to .snapshots/{notebook_name}_{timestamp}/

Cell-Specific Snapshot:

1. Pin cells using the pin icon in individual cell toolbars
2. Click "Save Cell Snapshot" in the notebook toolbar
3. Only pinned cells and their outputs are preserved
4. Ideal for capturing specific experimental results

Managing Snapshots

Gallery View:

• Click "Open Snapshot Gallery" to browse all saved snapshots
• View thumbnail previews of charts and visualizations
• Access detailed metadata including cell counts and creation times
• Click snapshot titles or notebook icons to view preserved states

Restoring Previous States:

• In the gallery, click the revert button (arrow icon) on any snapshot
• Confirm the restoration when prompted
• Your notebook will be restored to that exact state with all outputs

Direct Folder Access:

• Use "Open Snapshot Folder" command for filesystem access
• All snapshots organized in timestamped directories

Configuration

Configure the extension through VS Code settings:

{
    "mns.retention.keepMostRecent": 50,
    "mns.retention.maxAgeDays": 180
}

Available Settings

• mns.retention.keepMostRecent: Maximum snapshots per notebook (default: 50)
• mns.retention.maxAgeDays: Maximum age before automatic deletion (default: 180 days)

Snapshot Structure

Each snapshot creates an organized directory structure:

.snapshots/
└── notebook_20250828T173512Z/
    ├── manifest.json          # Complete metadata and configuration
    ├── notebook.ipynb         # Full notebook with all outputs (full snapshots)
    ├── cells.json            # Cell data only (cell snapshots)
    ├── images/               # Extracted visualizations and plots
    │   ├── cell3_out0.png    # PNG outputs from matplotlib, etc.
    │   └── cell7_out1.jpg    # JPEG outputs and images
    └── texts/                # Large text outputs saved separately
        └── cell5_out0.txt    # Text outputs over 4KB threshold

Available Commands

Access through Command Palette (Ctrl+Shift+P):

• Notebook Snapshots: Save Full Snapshot - Complete notebook state
• Notebook Snapshots: Save Cell Snapshot - Selected/pinned cells only
• Notebook Snapshots: Pin Cell - Mark cell for selective snapshots
• Notebook Snapshots: Unpin Cell - Remove cell from snapshot selection
• Notebook Snapshots: Open Snapshot Gallery - Browse saved snapshots
• Notebook Snapshots: Open Snapshot Folder - Direct filesystem access
• Notebook Snapshots: Revert to Snapshot - Restore notebook state

Requirements

• VS Code 1.74.0 or newer
• Jupyter extension for VS Code
• Python environment with Jupyter kernel support

Technical Details

Supported Output Types

• PNG and JPEG images from matplotlib, plotly, seaborn
• HTML outputs and interactive widgets
• Plain text and formatted text outputs
• Error messages and stack traces
• Data tables and structured output

File System Organization

• Snapshots stored alongside notebook in .snapshots directory
• ISO 8601 timestamp naming for consistent sorting
• JSON manifests enable fast metadata queries
• Extracted files use predictable naming conventions

Troubleshooting

Gallery Not Showing Thumbnails

• Ensure notebook contains image outputs (PNG/JPEG)
• Check that .snapshots directory is accessible
• Restart VS Code if thumbnails don't appear

Snapshot Restoration Issues

• Verify the target notebook file is not read-only
• Close other editors with the same notebook open
• Check VS Code output panel for detailed error messages

Performance with Large Notebooks

• Consider using cell snapshots for notebooks with many outputs
• Adjust retention settings to limit storage usage
• Large images are extracted to separate files automatically

Contributing

Contributions welcome for:

• Enhanced output format support
• Performance optimizations for large notebooks
• Additional gallery features and filtering
• Integration with version control systems

License

MIT License - see LICENSE file for details.

Changelog

1.0.0

• Initial marketplace release
• Full notebook snapshot functionality with output preservation
• Cell-specific snapshot support with pin/unpin management
• Visual gallery browser with thumbnail previews
• One-click notebook restoration from any snapshot
• Configurable retention policies with automatic cleanup
• Smart output extraction for images and large text files
• Comprehensive metadata tracking and organization