A couple of years ago, I got lucky and found Daniel Roy Greenfeld's dj-notebook project thanks to a reddit post. I wrote about it here. It's held up well. I still find it very useful in almost any context where I'd run python manage.py shell to help me understand what's going on with a django site. My preferences for using notebooks have evolved since then, though. Lately, I find marimo notebooks more suited to the way I like to use (and re-use) notebooks than jupyter. They're easier to deal with in git, easier to share, and they don't have the same tendency to depend on hidden state. While they're also, as a consequence, a bit less flexible, they strike a better balance for me.

So this weekend, I wanted to see how they'd work with django.

I was expecting to need to fork the dj-notebook project and add marimo-specific integration, then hopefully get that merged upstream. Instead, I was happily surprised when everything just work. I suppose I still have a documentation patch to offer upstream, and this blog post is a stash for my notes on that.

This post references my toy django contacts application that I put together follwing the exercises in the excellent Hypermedia Systems book. I wrote about those as I did them, and I just updated that app to use django 6, python 3.13, uv, ruff, prek and pytest. You can grab the code if you want a low-friction way to try out these notebooks without modifying a real project.

Marimo notebook with Django ORM

Aside: I use uv to manage my dependencies and my runtime, and the examples here will use it too. But it’s not essential. The project includes an equivalent requirements.txt file, and any packages that I add using uv could be added to an activated venv created from that requirements.txt using the pip command. But uv is easier, faster and less error-prone. You should use it, too.

Setup

I like to put my notebook dependencies in a separate group, since I don’t usually install those on my production servers. I’m not aware of any specific hazard to that apart from increasing the install size. Jupyter amd marimo pull in many dependencies, and when I use them I tend to mirror my data to a test server first. And for now, we’ll be installing all of both of them here. It may be worth contributing a patch to dj-notebook that offers optional jupyter/marimo dependencies instead.

uv add --group=notebook dj-notebook marimo

If you’ve previously sync’d the uv virtual environment without that group, you may also need to run

uv sync --group=notebook

Then just as a matter of keeping my project cleaner, I like to create a notebooks directory at the top level and stash any notebooks I want to commit in there.

Usage

Run marimo edit notebooks/repl.py and open the resulting link in your browser of choice.

At the top of the notebook, activate your django environment:

from dj_notebook import activate
plus = activate()

And then your models and several interesting utilities are available from plus. See the dj-notebook documentation for details. Two that I find useful, frequently, are inheritance diagrams and dumping querysets into dataframes.

plus.read_frame(plus.Contact.objects.all())

plus.diagram(plus.Contact)

I think there are some improvements I could make and offer back to dj-notebook, but I was quite impressed that this just worked.