Deepnote turns notebooks into editable projects

Deepnote’s open repo lets you convert Jupyter notebooks into editable .deepnote projects in VS Code, Cursor, or Windsurf.

I've been living in notebook land long enough to know when something is pretending to be simpler than it is. Jupyter always gave me the same little tax: messy JSON, fragile cell state, and that annoying moment where I’d wonder whether the notebook was actually reproducible or just lucky. Then AI editors showed up and made the whole thing more awkward. I wanted to edit notebooks in VS Code or Cursor, but I didn’t want another half-working bridge that treated notebooks like second-class citizens.

Deepnote’s open-source repo finally made me stop squinting. It isn’t just “a notebook UI with AI sprinkled on top.” It’s trying to make notebooks into a project format I can version, convert, and run locally without giving up the option to move into Deepnote Cloud later. That’s the part that got my attention. The repo says it’s a drop-in replacement for Jupyter, but the interesting bit is the workflow: convert, edit, run, sync, and only then decide whether you need the cloud.

That’s a much saner order.

I found the repo on GitHub, and the official docs on Deepnote fill in the product side. The repo itself is where the useful mechanics live: .deepnote files, conversion tooling, block types, and editor support for VS Code, Cursor, and Windsurf. That’s the angle I’m breaking down here: not “what is Deepnote,” but how to use this repo like a developer who wants notebook sanity instead of notebook theater.

Stop treating notebooks like disposable blobs

Human-readable format: The .deepnote YAML format replaces .ipynb's messy JSON with clean, version-control and human-friendly structure for projects and notebooks.

What this actually means is that Deepnote is trying to fix one of the ugliest parts of notebook work: the file format. I’ve opened enough .ipynb files in a diff view to know the pain. You’re not reading code changes. You’re reading output noise, metadata churn, and whatever random state got serialized last.

Deepnote’s answer is the .deepnote format, which is YAML instead of JSON. That matters because YAML is readable by humans and friendlier to version control. I don’t need a parser just to spot what changed in a notebook project. I can actually glance at it and understand the structure.

There’s also a bigger idea hiding here: Deepnote isn’t just converting a notebook file, it’s converting the notebook into a project. That means multiple notebooks, integrations, and settings can live together in one structured unit. I’ve run into this when teams keep a notebook, a data connection, and a bunch of ad hoc notes in separate places. That works until someone else needs to pick it up. Then it becomes archaeology.

How to apply it: if you’re still shipping notebooks as isolated .ipynb files, start by converting one real project and storing the .deepnote output in Git. Don’t do this on a toy example. Use a notebook that already has imports, SQL, charts, and a data connection if you have one. The point is to see whether the project structure helps you reason about the work.

• Keep source notebooks under version control as .deepnote instead of raw .ipynb.
• Use the YAML structure to separate notebook logic from outputs and metadata noise.
• Prefer project-level organization when the work includes multiple notebooks or shared settings.

Blocks are the part that makes this feel less like a notebook hack

Block-based architecture: Extend notebooks beyond code cells with blocks for SQL, inputs, charts, and much more — all defined and validated through the open @deepnote/blocks package.

What this actually means is that Deepnote is not pretending every notebook problem fits into a Python code cell. That’s refreshing, honestly. I’ve lost count of how many times I’ve seen people force SQL, parameters, UI inputs, and charts into awkward cell patterns because the notebook tool only knew “code” and “markdown.”

Deepnote’s block model gives those pieces first-class status. The repo points to the open @deepnote/blocks package, which defines and validates block types like Code, SQL, Text, Markdown, Input, Visualization, Button, Big Number, Image, and Separator. That’s a much more honest model of data work. Real notebooks are not just executable code. They’re a mix of computation, parameters, display, and workflow controls.

I ran into this exact problem when I tried to keep a notebook parameterized for different datasets. The old pattern was a clumsy combo of variables, comments, and “remember to change this before running.” That’s not a workflow. That’s a footgun with a notebook icon.

How to apply it: if you maintain notebooks for analysis or internal reporting, identify the stuff that is not really code. Turn filters, date ranges, and dataset selectors into explicit input blocks. Put SQL in SQL blocks. Put charts in visualization blocks. The win is not visual polish. The win is that the notebook becomes easier to run correctly by somebody who didn’t write it.

If you want the deeper API side, the repo’s structure makes it clear that blocks are meant to be reusable and validated, not just rendered. That’s the difference between a notebook UI and a notebook system.

Conversion is the real escape hatch

Effortless conversion: Convert .ipynb notebooks into .deepnote projects and back again using the open @deepnote/convert CLI and API.

What this actually means is that Deepnote is not asking you to burn the bridge to Jupyter. Good. I don’t trust tools that demand a full migration before they’ve earned it. The conversion layer is the practical part of the repo, because it lets you test the format without committing your whole stack to it.

The README shows a simple starting point:

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

That’s the kind of thing I wish more notebook tools led with. Not a giant onboarding ceremony. Just convert the file and open it in your editor. The repo also says you can go back and forth between formats, which matters if you collaborate with people who still live in Jupyter or if you need to keep compatibility with existing workflows.

I’ve seen teams get stuck because one person wants a better notebook format, but the rest of the group is still tied to old files. Bidirectional conversion is what makes this realistic instead of aspirational. It lowers the social cost of trying the tool.

How to apply it: pick one notebook that already has a few cells, some output, and maybe a chart. Convert it to .deepnote, open it in your editor, and inspect what changed. Then convert it back. You’re looking for two things: whether the round trip preserves the parts you care about, and whether your team would tolerate the new format in Git.

• Use the CLI for batch conversion when you’re migrating a folder, not just one file.
• Use the API if you want conversion inside a Node.js or TypeScript workflow.
• Test round-trip fidelity before you standardize on the format.

Local editing is the real selling point, not the cloud pitch

What can you do right now? This open-source repository lets you, edit and run Deepnote notebooks directly in your favorite AI-native code editors: VS Code extension - Full Deepnote support in Visual Studio Code Cursor extension - AI-powered notebook editing in Cursor Windsurf extension - Collaborative development in Windsurf

What this actually means is that Deepnote is trying to meet developers where they already work. That matters more than the cloud pitch. I like cloud notebooks when I need shared compute or collaboration, but I do not want to be trapped in them just to inspect or edit a notebook.

The repo explicitly supports VS Code, Cursor, and Windsurf. That’s useful because these are the places a lot of us already spend our day. If notebook editing can happen there, the tool stops being a separate destination and becomes part of the normal dev workflow.

I’ve had this exact annoyance with older notebook tooling: you’d write analysis in one place, then jump into a different UI to fix a tiny cell issue, then jump back to your editor for the rest of the codebase. It’s friction for no good reason. Deepnote’s local story is better because it starts with the editor, not the platform.

How to apply it: if your team already uses one of these editors, install the Deepnote extension and treat it like a notebook-first file type rather than a special export format. Keep the notebook close to the rest of your code. That makes refactoring, review, and AI-assisted editing much less annoying.

The repo also mentions the Deepnote Toolkit and related extensions, which tells me this is meant to be an ecosystem, not a one-off plugin. That’s the part worth watching if you care about long-term workflow fit.

Reactive execution is the part that saves you from stale results

Reactive notebook execution: Automatically re-runs dependent blocks when inputs or data change, ensuring notebooks stay consistent and reproducible without manual execution.

What this actually means is that Deepnote is trying to kill the “I changed one thing and forgot to rerun half the notebook” problem. If you’ve used notebooks seriously, you know this bug. It’s not a small bug either. It’s the kind that makes results look valid when they’re actually stale.

Reactive execution means dependent blocks re-run when inputs or data change. That sounds simple, but it’s a big deal for reproducibility. Instead of relying on the human operator to remember execution order, the notebook tracks dependencies and updates the right pieces.

I’ve been burned by this in analysis work more than once. A chart looked right because the output cell was old, not because the code was correct. That’s a terrible failure mode. Reactive execution doesn’t solve every notebook problem, but it removes one of the dumbest ones.

How to apply it: use dependency-aware execution for any notebook that feeds a report, dashboard, or decision. If a cell depends on a date input, a SQL query, or a data load step, make sure the execution model reflects that dependency. Don’t let manual reruns be the thing holding your analysis together.

This is also where the block model and the project format start to make sense together. Structure plus execution rules equals fewer surprises. That’s the actual value, not the UI gloss.

Deepnote is trying to be a bridge, not a rewrite

Deepnote is a drop-in replacement for Jupyter. It uses the Deepnote kernel, which is more powerful but still backwards compatible, so you can seamlessly move between both, but it adds an AI agent, sleek UI, new block types, and native data integrations.

What this actually means is that Deepnote is positioning itself as an extension of the Jupyter world, not a hostile replacement. I appreciate that. A lot. The Jupyter ecosystem is too embedded in real work to pretend otherwise. If a tool wants adoption, it needs to respect the existing notebook universe.

The repo also says Deepnote is built on the Jupyter kernel and keeps compatibility with existing notebooks. That’s the practical part. You can bring old work in, work on it locally, and still move it into Deepnote Cloud when you need team collaboration or more compute. The repo’s own comparison table makes the split clear: Deepnote offers zero setup via cloud or local installation, native AI features, built-in Git integration, sharing by link, managed cloud compute, and native database/API connections. Jupyter gives you local resources and manual configuration. Different tradeoffs, same basic lineage.

I like that this repo is honest about where Jupyter still fits. It’s not saying “Jupyter was bad.” It’s saying “Jupyter got us here, and now we need a better workflow on top of it.” That’s a much more credible pitch.

How to apply it: treat Deepnote as a compatibility layer with better ergonomics. Start locally, keep compatibility in mind, and only move to the cloud when collaboration or compute actually justify it. That’s how you avoid a migration that turns into a religion.

If you’re in academia, the repo also notes that Deepnote Cloud is free for students and educators, and it includes a citation format for research use. That’s a nice sign that the team expects real scientific workflows, not just demo notebooks.

The template you can copy

# Deepnote notebook workflow template

## 1) Convert an existing notebook
npx @deepnote/convert notebook.ipynb

## 2) Open the generated project in your editor
# VS Code, Cursor, or Windsurf
# Edit the .deepnote project directly

## 3) Organize the notebook as blocks
- Code blocks for Python/R logic
- SQL blocks for queries
- Input blocks for parameters like dates, filters, and dataset names
- Visualization blocks for charts
- Markdown/Text blocks for notes and explanations

## 4) Keep the project version-controlled
- Commit the .deepnote project to Git
- Review YAML diffs instead of raw .ipynb JSON
- Prefer one project folder for related notebooks and settings

## 5) Use reactive execution rules
- Re-run dependent blocks when inputs change
- Avoid manual reruns as your only safety net
- Check that charts and outputs are tied to current inputs

## 6) Round-trip before you standardize
npx @deepnote/convert notebook.deepnote --outputFormat ipynb

## 7) Use the cloud only when it solves a real problem
- Shared collaboration
- Managed compute
- Team workflows
- Native data integrations

## 8) Minimal migration checklist
- Pick one notebook with real outputs
- Convert it to .deepnote
- Open it in your editor
- Verify block structure and outputs
- Convert it back to confirm compatibility
- Decide whether the new format is worth adopting team-wide

The repo that triggered this is deepnote/deepnote on GitHub. I’ve summarized and reorganized the workflow above, but the underlying ideas, file formats, and tooling come from Deepnote’s open-source project and README, not from me.