Deepnote Open Source: a .deepnote YAML notebook format with a conversion CLI

The problem: .ipynb diffs are noisy and cells are the only unit

A Jupyter notebook is JSON. Source code, base64 image outputs, execution counts and kernel metadata all sit in one file, so a one-line code change can produce a diff that touches dozens of lines. Deepnote's answer is a YAML project format called .deepnote. The README describes it as replacing "`.ipynb`'s messy JSON with clean, version-control and human-friendly structure", with each notebook in its own .deepnote file alongside its integrations and settings so diffs stay focused.

The second change is the unit of work. Instead of code cells only, the format is block-based: the @deepnote/blocks package defines Code, SQL, Text, Markdown, Input, Visualization, Button, Big Number, Image and Separator blocks, and converts blocks into executable Python. Input blocks cover text, textarea, checkbox, select, slider, file, date and date-range types. If your notebooks are mostly Python cells, this is more structure than you need. If you have been pasting SQL strings and widget boilerplate into cells, the block types map onto work you already do.

How the format and the conversion CLI fit together

Three packages do the visible work. @deepnote/blocks holds TypeScript types and utilities, including Python code generation and markdown conversion for text blocks. @deepnote/convert is both a CLI (`deepnote-convert`) and a programmatic API for Node.js and TypeScript, and it is bidirectional: any supported format into Deepnote, and Deepnote back out via `--outputFormat`. @deepnote/local-runner, released at 0.1.0 on 2026-08-13, is the newest of the three and the one whose surface is least settled.

Conversion is not lossy by design. The README states that notebooks imported from Google Colab, Amazon SageMaker, Kaggle or Azure ML keep their platform-specific metadata through a round trip. That is the claim worth testing on your own files, because platform metadata is exactly what usually gets dropped.

Outputs are handled separately from source. FILES.md documents a .snapshot.deepnote format that keeps outputs out of the notebook file for cleaner Git history, with a `contentHash` field that records which code produced each output. That is a provenance mechanism, not just a storage split: it lets you detect when a stored output no longer matches the code next to it. The README does not document rollback of snapshots, so treat snapshot lifecycle management as something to read up on in FILES.md before you build a workflow around it.

Installing the convert CLI and converting a first notebook

The README's getting-started path is a single npx invocation, with no global install and no Python environment to prepare. Run it in the directory holding your notebook:

npx @deepnote/convert notebook.ipynb # This will convert the notebook and create notebook.deepnote

According to the README, this creates a file named notebook.deepnote next to the input. The comment in the command is the README's own. The CLI is also available as the `deepnote-convert` command for batch conversions, so a directory of notebooks can be handled in one pass rather than one npx call per file.

To read or edit the result, the project points at three editor extensions rather than a bundled application: the VS Code extension from the Visual Studio Marketplace, and the Cursor and Windsurf extensions from Open VSX, all published under the Deepnote.vscode-deepnote identifier. Open the .deepnote file in one of those editors. The repository also carries runnable examples under examples/, including 1_hello_world.deepnote and 2_blocks.deepnote, which are the fastest way to see what a valid file looks like before you write one by hand.

For repository work rather than CLI use, the root package.json defines the standard scripts: `pnpm build`, `pnpm test` (vitest), `pnpm typecheck`, and `pnpm lintAndFormat` for Biome plus Prettier. Note that `pnpm run license-check` allows only MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause and ISC in the dependency tree, which tells you the project takes its own dependency licences seriously.

Where the open-source repo stops and the cloud product starts

This is the part most people get wrong. The repository contains packages, a format specification, a CLI and editor extensions. It does not contain the Deepnote Cloud application. The roadmap section states plainly that you will "soon" be able to run the familiar cloud UI locally, edit notebooks with a local AI agent, bring your own keys for AI services, and run your own compute. Those are future items, not current capabilities.

So the AI agent, real-time collaboration, managed compute and shareable data apps described in the README's comparison table are cloud features. The comparison table itself is written from the product's point of view and should be read that way: rows like "Zero setup via cloud or local installation" and "Built-in Git integration" describe the Deepnote product overall, not the open-source packages alone. The open-source side gives you the file format, the conversion tooling and the editor integration. Everything else requires the hosted service.

One practical consequence: if you want the reactive execution model, where dependent blocks re-run when inputs or data change, the README describes it as a Deepnote property but does not document how to enable it in a local editor session. Confirm that before assuming it works offline.

Conversion round trips are the real risk, not the format

The honest limitation is that a new notebook format only pays off if the round trip is clean, and round trips are where metadata goes missing. The README makes a specific promise here: platform-specific metadata from Colab, SageMaker, Kaggle and Azure ML is preserved during roundtrip. It does not say what happens to outputs, execution counts, or kernel state that has no Deepnote equivalent. The snapshot format suggests outputs live in a separate file, so a naive conversion of a notebook with heavy inline outputs may produce a different file layout than you expect.

The second limitation is ecosystem reach. Jupyter has years of extensions, magics and third-party tooling built around .ipynb. A .deepnote file is not readable by JupyterLab, nbconvert or any tool that expects JSON. You are adopting a format that only Deepnote's own tooling reads, even though the runtime is built on the Jupyter kernel for notebook compatibility. That is a real lock-in cost, offset only by the fact that conversion back to .ipynb is supported.

Finally, this is the wrong tool if you need a hosted, multi-user notebook service today and do not want to run anything yourself. Nothing in the repository provides that.

Deepnote versus Jupyter and Colab in practice

The closest comparison is plain Jupyter, and the difference is architectural rather than cosmetic. Jupyter's unit is the cell inside a JSON document; Deepnote's unit is a typed block inside a YAML file, with outputs optionally split into a snapshot file. Jupyter requires local installation and manual Git handling; Deepnote's README positions the cloud product as zero-setup with built-in Git integration. For version control specifically, the YAML format is the substantive difference, and it is one you can evaluate without touching the cloud at all.

Against Google Colab, the split is different. Colab is a hosted notebook environment tied to Google's infrastructure; Deepnote Open Source is a format and a toolchain you run locally, with the hosted equivalent being Deepnote Cloud. The README's conversion documentation explicitly names Colab as an import source, which means the project treats Colab notebooks as something to bring across rather than a competitor to replace. If your work lives in Colab and stays there, converting to .deepnote adds a step with no local benefit.

Licence, maintenance and what an upgrade costs you

The repository is Apache-2.0, and the root package.json carries the same identifier. Apache-2.0 includes an explicit patent grant and requires attribution and notice retention, which matters if you vendor the packages. The internal `license-check` script restricts dependencies to MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause and ISC, so the dependency tree is unlikely to introduce a copyleft obligation, though that script is a project policy and not a guarantee about every transitive package. This is a description of the licence text, not legal advice.

Maintenance signals are current: the last push was on 2026-09-10, and the most recent releases were @deepnote/[email protected], @deepnote/[email protected] and @deepnote/[email protected], all published on 2026-08-13. The version numbers tell their own story. runtime-core is at 0.5.0, mcp at 0.4.1, and local-runner at 0.1.0, so pre-1.0 APIs should be expected to move. An upgrade that touches @deepnote/blocks or @deepnote/convert can change generated Python or conversion output, which means the cost of upgrading is not just a dependency bump: it is re-verifying that your converted notebooks still execute and that round-tripped .ipynb files still match. Pin versions in CI and diff conversion output on upgrade rather than trusting a green test run.

Editorial conclusion

Adopt the open-source packages if you want a Git-friendly notebook format and a tested round-trip path for existing .ipynb files, and you are willing to run the CLI and extensions yourself. Do not adopt this repo expecting the Deepnote Cloud UI, the AI agent, or managed compute: the README lists those as roadmap items for local use, not as shipped open-source features. Before committing a team, convert one real notebook with platform metadata, confirm the round-trip back to .ipynb is byte-for-byte acceptable, and check the .snapshot.deepnote behaviour in FILES.md, because that is where the format's output handling is actually specified.

Frequently asked questions

Official sources

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