Deepnote Skill

.deepnote files are YAML-based, portable, git-friendly files that each hold a single notebook. Each notebook holds an ordered list of blocks (code, SQL, markdown, inputs, visualizations, etc.). Snapshot files (.snapshot.deepnote) use the same format but include execution outputs.

File Structure

A minimal valid .deepnote file:

version: 1.0.0
metadata:
  createdAt: "2025-01-08T10:00:00.000Z"
project:
  id: 2e814690-4f02-465c-8848-5567ab9253b7
  name: My Project
  notebooks:
    - id: e132b172-b114-410e-8331-011517db664f
      name: Main
      blocks:
        - id: b75d3ada977549b29f4c7f2183d52fcf
          blockGroup: 9dd9578e604a4235a552d1f4a53336ee
          type: code
          content: |
            print("Hello World!")
          sortingKey: a0
          metadata: {}

Top-level fields: version (required, "1.0.0"), metadata (required), project (required), integrations (optional), environment (optional).

Schema Reference

TypeScript schema — auto-generated types for .deepnote and .snapshot.deepnote files

Notebooks

Each entry in project.notebooks has:

id - UUID v4 identifier
name - Human-readable name
executionMode - block (run individually) or downstream (run with dependents)
blocks - Array of content blocks
workingDirectory - Optional base directory for file operations

Blocks

Every block has these common fields:

| Field | Description | | ------------ | --------------------------------------------------------------- | | id | Unique hex identifier (32 chars) | | blockGroup | Groups related blocks (same format as id) | | type | Block type string | | content | Source code, text, or query (YAML multi-line \| syntax) | | sortingKey | Determines display order (lexicographic, e.g. a0, a1, a2) | | metadata | Type-specific configuration object |

Block Types

| Category | Types | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Code | code | | SQL | sql | | Text | markdown, text-cell-h1, text-cell-h2, text-cell-h3, text-cell-p, text-cell-bullet, text-cell-todo, text-cell-callout | | Input | input-text, input-textarea, input-checkbox, input-select, input-slider, input-date, input-date-range, input-file | | Display | visualization, pivot-table, big-number, image, separator | | Other | button, notebook-function |

Block Type References

Integrations

Database connections stored in the top-level integrations array:

integrations:
  - id: 084f5334-5dbe-41c7-9020-3f66b9418062
    name: Production DB
    type: pgsql

Each integration has id (UUID), name, and type. Supported types: alloydb, athena, big-query, clickhouse, databricks, dremio, mariadb, materialize, mindsdb, mongodb, mysql, pgsql, redshift, snowflake, spanner, sql-server, trino. (Note: pandas-dataframe exists as a type but is not configurable via CLI.)

SQL blocks reference integrations via metadata.sql_integration_id.

Snapshots

Snapshot files (.snapshot.deepnote) store execution outputs separately from source.

Location

Snapshots are saved in a snapshots/ directory adjacent to the source file:

project.deepnote
snapshots/
  my-project_<projectId>_<notebookId>_latest.snapshot.deepnote
  my-project_<projectId>_<notebookId>_2025-01-08T10-30-00.snapshot.deepnote
  my-project_<projectId>_latest.snapshot.deepnote
  my-project_<projectId>_2025-01-08T10-30-00.snapshot.deepnote

Naming:

Single-notebook files: {slug}_{projectId}_{notebookId}_{timestamp}.snapshot.deepnote
Legacy files: {slug}_{projectId}_{timestamp}.snapshot.deepnote
slug — slugified project name
projectId — UUID from project.id
notebookId — notebook UUID (for single-notebook files)
timestamp — latest or ISO 8601 (e.g. 2025-01-08T10-30-00)

Reading Snapshot Data (token-efficient)

Use CLI commands — they're cross-platform and avoid loading the full YAML:

deepnote cat snapshots/*_latest.snapshot.deepnote                    # All block outputs
deepnote cat snapshots/*_latest.snapshot.deepnote --type code        # Only code outputs
deepnote inspect snapshots/*_latest.snapshot.deepnote                # Metadata + summary
deepnote inspect snapshots/*_latest.snapshot.deepnote -o json        # JSON for parsing

Do not read snapshot files directly — always use CLI commands or MCP tools to inspect them.

Diagnosing Errors

When execution fails, check the latest snapshot:

execution.summary — blocksExecuted, blocksSucceeded, blocksFailed, totalDurationMs
execution.error — name, message, traceback (top-level error)
Per-block outputs — individual blocks have error output_type with ename, evalue, traceback

Quick error check:

deepnote inspect snapshots/*_latest.snapshot.deepnote -o json
deepnote run project.deepnote -o json   # Errors inline in output

Content Hash Verification

Each block in a snapshot has contentHash (SHA-256). If block content changed since the snapshot, the hash won't match — the output is stale.

Latest vs Timestamped

| Aspect | _latest | Timestamped | | ----------- | ----------------------------------- | ---------------------- | | Updated | Overwritten on each run | Immutable, one per run | | Consistency | May mix outputs from different runs | All from same run | | Use case | Quick access to recent results | Audit trail |

Editing Guidelines

When creating or modifying .deepnote files:

Block IDs - Generate random 32-character hex strings (e.g. crypto.randomUUID().replace(/-/g, ''))
Block groups - Each block needs a blockGroup (same hex format); blocks in the same group share a group ID
Sorting keys - Use lexicographic strings: a0, a1, ..., a9, b0, etc. Insert between existing keys for ordering
Content - Use YAML literal block scalar (|) for multi-line content to preserve newlines
Metadata - Use {} for defaults; add type-specific fields as needed

Important Policies

Stay in .deepnote format. When something goes wrong, do not fall back to converting to .ipynb and working in Jupyter format. The .deepnote format has better debugging tools (deepnote inspect, deepnote cat, deepnote lint, deepnote dag) that are not available for .ipynb files. Stay in .deepnote and use these tools to diagnose and fix issues.
Only convert on explicit request. Only use deepnote convert to export when the user explicitly asks for a format conversion.

Running After Edits

After creating or modifying blocks, always run the project to verify changes.

Prerequisites

Check if the CLI is installed:

deepnote --version

If not installed, find the best available Python and install via pip:

IDE interpreter — check for a deepnote.json file in .vscode/, .cursor/, or .antigravity/ (see IDE Interpreter Detection below) and use its pythonInterpreter (or, for older sidecars without one, the interpreter inside venvPath)
Project instructions — if the project has a .python-version file or pyproject.toml with requires-python, use the specified version
Project venv — look for .venv/bin/python, venv/bin/python, or env/bin/python
Homebrew Python — check if /opt/homebrew/bin/python3 or brew --prefix python3 exists
System Python — use python3 (preferred) or python

Install with the best available Python (must be >= 3.9):

<best-python> -m pip install deepnote-cli

If no suitable Python is available, install via npm instead:

npm install -g @deepnote/cli

IDE Interpreter Detection

The Deepnote extension for VS Code, Cursor, and Antigravity records the interpreter selected for each notebook in a deepnote.json sidecar file in the workspace root:

.vscode/deepnote.json
.cursor/deepnote.json
.antigravity/deepnote.json (Antigravity)

The file maps project IDs to interpreters:

{
  "mappings": {
    "<project-id>": {
      "pythonInterpreter": "/path/to/python"
    }
  }
}

Older extension versions managed a virtual environment per project and also recorded environmentId and venvPath for it; both are optional, and venvPath is only used as a fallback when no pythonInterpreter is recorded. Both shapes are pinned as fixtures in test-fixtures/ide-sidecar/.

deepnote run, analyze, lint, dag, and the MCP deepnote_run tool read this file automatically: when --python / pythonPath and DEEPNOTE_PYTHON are both unset, they look the file's project.id up in every deepnote.json from the notebook's directory upward, plus the extra roots each tool searches (DEEPNOTE_WORKSPACE for the CLI, plus --cwd for run only; the workspace root, DEEPNOTE_WORKSPACE or the server's cwd, for the MCP server), and use the recorded interpreter. You do not need to pass --python for a notebook whose interpreter is already selected in the extension. The output says which interpreter was used and where it came from (source: ide).

Pass --python only to override that choice. To install deepnote-cli into the same environment, use the interpreter the tools resolved (deepnote run prints it): the sidecar's pythonInterpreter, or for an older sidecar without one, the interpreter inside its venvPath:

<resolved-python> -m pip install deepnote-cli

At run time the full order is: --python / pythonPath, then DEEPNOTE_PYTHON, then the IDE environment above, then a .venv or venv directory from the notebook's directory upward that has deepnote-toolkit installed (source: venv; one without the toolkit is skipped with a warning rather than picked), then the system Python. The installation checklist earlier in this section is only about where to install deepnote-cli; it does not affect which interpreter a run uses.

Running

deepnote run project.deepnote                         # Run full project
deepnote run project.deepnote --notebook "Analysis"    # Specific notebook
deepnote run project.deepnote --block abc123           # Specific block
deepnote run project.deepnote --dry-run                # Preview only
deepnote run project.deepnote -o json                  # JSON output

Checking Results

Inline output — stdout/stderr printed directly
Snapshot — outputs saved to snapshots/ directory (see Snapshots section above)
Exit codes — 0 success, 1 runtime error, 2 invalid usage
JSON — use -o json for structured per-block results

Workflow

Edit the .deepnote file
Run: deepnote run project.deepnote
If errors, check snapshot for details
Fix and re-run

Apps and Streamlit apps

Use app for HTML, CSS, and JavaScript hosted by Deepnote, and Streamlit app for a Python UI. Start with Build and publish apps and Streamlit apps:

Choose the workflow from the user's framework, hosting target, and audience.
Prepare and verify its notebook, Streamlit entrypoint, or browser build.
Follow Publish apps and Streamlit apps for an app or Streamlit app.
Test the hosted URL as the intended viewer, including notebook runs and API access when used.

CLI Quick Reference

| Command | --------------------------------------- | deepnote run [path] | deepnote convert <path> | deepnote inspect [path] | deepnote cat <path> | deepnote diff <a> <b> | deepnote validate <path> | deepnote lint [path] | deepnote stats <path> | deepnote analyze <path> | deepnote dag show\|vars\|downstream | deepnote split <path> | deepnote open <path> | deepnote schedule <path> | deepnote publish <dir> | deepnote static-site access | deepnote streamlit publish <file> | deepnote sync [dir] | deepnote integrations pull\|add\|edit | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Execute notebooks (.deepnote, .ipynb, .py, .qmd) | | Convert between formats (Jupyter, Quarto, Percent, Marimo) | | Display file metadata | | Display block contents | | Compare two files | | Schema validation | | Check a .deepnote or integrations yaml file for issues | | Project statistics | | Comprehensive analysis with quality score | | Dependency analysis | | Split a multi-notebook file into one .deepnote per notebook. The init notebook (if any) becomes its own standalone file; each main file keeps initNotebookId so deepnote run resolves and runs the sibling init as a prelude. | | Open in Deepnote Cloud | | Create, update, or remove (--remove) a notebook's recurring Deepnote Cloud schedule | | Publish an app from a build directory. | | Enable or disable sharing and viewer API access for an existing app without changing its files. | | Serve a file already in the project as a Streamlit app. | | Sync Deepnote Cloud projects with a local directory, both ways: pull every project into <folder path>/<project name>/ (one .deepnote per notebook), push local edits back (the exact-inverse ZIP import). State in .deepnote-sync.json; conflicts prompt (or --on-conflict skip\|override). | | Manage database integrations in the local integrations file |