Deepnote Open Source: A YAML Notebook Format With a Jupyter Kernel Underneath

The Problem Is the Diff, Not the Notebook

Jupyter notebooks are JSON documents that mix source code, cell outputs, execution counters, and editor metadata in one file. That mixture is why reviewing a notebook change in a pull request is unpleasant: a single re-run can rewrite base64 image data and execution counts across the file, and the actual code change disappears inside it. Deepnote's answer is a format swap. The README describes the .deepnote YAML format as replacing the .ipynb JSON with what it calls a clean, version-control and human-friendly structure, with each notebook in its own .deepnote file alongside its integrations and settings. The stated goal is that diffs stay focused. The audience is anyone who has ever asked a colleague to re-run a notebook before merging, and data teams that keep notebooks in the same repository as the code they depend on.

Source and Outputs Live in Separate Files

The mechanism that makes the diff argument concrete is snapshots. The repository's FILES.md specification, referenced from the README, documents both the .deepnote format and a .snapshot.deepnote format. The split is deliberate: snapshots separate outputs from source code for cleaner Git history. Outputs that change on every run move into a snapshot file, and the notebook file holds the code. The specification also defines a contentHash field that the README describes as providing code provenance, verifying which code produced each output. That is a stronger claim than clean diffs. It means a saved output carries an identifier tying it to the code that generated it, so a stale chart can be detected rather than trusted. I have not verified how the hash is computed or what happens when a block is edited after a snapshot is taken; the README does not say, and the specification is not reproduced here. Treat the provenance property as documented, not demonstrated.

Blocks Are a Typed Layer Over Python Code Generation

Deepnote notebooks are not just code cells. The @deepnote/blocks package defines TypeScript types for Code, SQL, Text, Markdown, Input, Visualization, Button, Big Number, Image, and Separator blocks, and it converts blocks to executable Python code. Input blocks cover text, textarea, checkbox, select, slider, file, date, and date-range widgets. The architectural consequence is that a notebook is a structured document that compiles down to Python, rather than a list of strings sent to a kernel. That is what makes reactive execution possible in principle: if inputs and SQL blocks are typed objects with declared dependencies, the runtime can re-run dependent blocks when an input changes. The README lists reactive notebook execution as a feature, describing automatic re-runs of dependent blocks when inputs or data change. The same typing is what lets a converter map a Deepnote input block onto something meaningful in another format. The cost is that the block model is now a specification you depend on. A .deepnote file written by a future version of @deepnote/blocks may not open in an older editor extension, and the README gives no compatibility policy for the file format across package versions.

Getting a Notebook Converted and Open

The README gives one command for the first step: npx @deepnote/convert notebook.ipynb, which converts the notebook and creates notebook.deepnote. The result is opened in VS Code, Cursor, or Windsurf through the Deepnote extension, published on the VS Code Marketplace and on Open VSX. The @deepnote/convert package also ships a deepnote-convert command for batch conversions and a programmatic API for Node.js and TypeScript applications, with bidirectional conversion controlled by an --outputFormat flag. Supported input formats are Jupyter .ipynb, Quarto .qmd, percent-format .py using # %% separators, and Marimo .py using @app.cell decorators. The README states that platform-specific metadata from Google Colab, Amazon SageMaker, Kaggle, and Azure ML is preserved during roundtrip conversion. That claim is the one I would test first, because metadata preservation is exactly where converters tend to lose information quietly. The three published package versions in the release list, @deepnote/runtime-core 0.5.0, @deepnote/mcp 0.4.1, and @deepnote/local-runner 0.1.0, all carry pre-1.0 version numbers. The local runner at 0.1.0 is the newest and least settled piece, which is consistent with the README placing local UI, a local AI agent, bring-your-own-keys, and self-hosted compute on the roadmap rather than in the current feature set.

What the Open Repository Does Not Include

The gap between the README's comparison table and the repository contents is the most important thing to understand before adopting anything. The table contrasts Deepnote with Jupyter on setup, AI features, version control, sharing, compute, and integrations, and Deepnote wins every row. But several of those rows describe Deepnote Cloud, not the Apache-2.0 code in this repository. Sharing with a link, managed cloud compute, and real-time collaboration are cloud features. The README is explicit that the open source offering covers working locally before scaling to the cloud, and the roadmap section confirms that running the familiar cloud UI locally, a local AI agent, bring-your-own-keys for AI services, and running your own compute are all things you will soon be able to do. Soon is doing real work in that sentence. If your reason for looking at Deepnote is the AI agent, the open repository does not give it to you today. What it gives you is the file format, the converter, the block types, and editor extensions that run against a Jupyter-compatible kernel.

The Alternative Is Jupyter With Extra Steps, or Something Else Entirely

The honest comparison is not Deepnote versus Jupyter as products, because the open source repository is a subset of one side of that table. It is Deepnote's format versus the alternatives for keeping notebooks reviewable. Jupyter with nbstripout or jupytext attacks the same diff problem from the other direction: keep .ipynb as the source of truth and strip outputs before commit, or pair the notebook with a percent-format .py file that Git can diff. That approach requires no new file format and no editor extension, and it keeps you inside the standard Jupyter ecosystem, but it does not give you typed input blocks or a contentHash tying outputs to code. Marimo takes a third position, storing notebooks as pure Python with @app.cell decorators and a reactive execution model, which means a Marimo notebook is a Python file that runs as a script. Deepnote's converter reads Marimo files, which is a useful admission that the formats are close enough in intent to translate. The difference is that Marimo treats Python as the storage format, while Deepnote treats YAML as the storage format and generates Python from it. If your team's objection to notebook formats is that they are not plain Python, Deepnote does not answer that objection. It answers the diff objection.

Licence, Versioning, and the Cost of a Pre-1.0 Format

The repository is Apache-2.0, which permits commercial use, modification, and redistribution with the usual conditions around notices and patent grants. The packages are published under the @deepnote scope on npm. Nothing in the supplied material describes a contributor licence agreement, a trademark policy for the Deepnote name, or how the cloud service and the open source packages are governed relative to each other, so I cannot tell you whether the open packages are a loss leader or a genuine independent surface. That ambiguity matters for a format you would commit to a repository. The upgrade cost is the format itself. @deepnote/runtime-core sits at 0.5.0 and @deepnote/local-runner at 0.1.0, and the README describes the file format as defined and validated through the open @deepnote/blocks package. A pre-1.0 validator can change its rules, and every .deepnote file your team has committed inherits that risk. The mitigating factor is the converter: because @deepnote/convert reads and writes Jupyter, Quarto, percent, and Marimo formats, an exit path exists in principle. Whether a roundtrip through .deepnote and back to .ipynb preserves your notebook is the thing to verify before you move a working project into the format, not after.

Editorial conclusion

Adopt the local tooling if your team already fights .ipynb diffs in code review and you want to keep running notebooks in VS Code or Cursor against a Jupyter-compatible kernel. Do not adopt it expecting the Deepnote Cloud UI, a local AI agent, or bring-your-own-key AI to run on your machine: the README lists those under Roadmap, not under what works today. Before committing, run npx @deepnote/convert on one real notebook from your repository, commit the resulting .deepnote file, and inspect the diff yourself. That single test tells you whether the format earns its place in your workflow.

Official sources

1. deepnote/deepnote on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases