Sandboxing

00:00 In the previous lesson, I showed you how to add UI components to your notebook. This is the first of two lessons about how to share your notebooks. I’ll start out by showing you how to package your dependencies for better reproducibility.

00:14 The save file for a marimo notebook is a Python script, which means you can manage it with tools like Git if you want to. It also has other features, though, to make it simpler to share more complex notebooks.

00:26 In a couple of the examples I’ve used in the course, my notebooks have had installation dependencies. In one, you needed NumPy, in the other, Matplotlib.

00:35 As you’re probably aware, Python isn’t the friendliest language when it comes to dependency management and packaging. To help you out, marimo comes with a sandboxing feature. When you operate in sandbox mode, the notebook manages a virtual environment for your dependencies.

00:51 The environment it uses is created on the fly and removed when you close things out. Since the environment is built and torn down with each use, the process needs to be kind of speedy.

01:02 As such, marimo has chosen to use the uv packaging tool to handle all of this stuff.

01:09 The sandbox flag is how you work in sandbox mode. You can create a new empty sandbox with the new command. In fact, that command works without the sandbox flag, creating a new empty notebook.

01:21 So it isn’t anything special. It’s the sandbox part that we’re interested in here. Edit is what you’ve been doing all along. If you use the edit subcommand with a new file, it creates it, or if you use it with an existing file, it opens it.

01:35 Adding the sandbox flag puts you into sandboxing mode.

01:40 Remember, earlier when I mentioned read-only mode? The run command is how you do this, and like the other two, it can be used with the sandbox flag as well.

01:49 I’m going to stick with what I’ve been doing so far, which is the middle command here, edit. I’m just going to add the sandbox flag before calling it.

01:57 Remember, for all this to work, you have to have uv installed first.

02:02 Running the edit command in sandboxing mode took about a second on my machine, and one second later. I’m in a new notebook called packages.py.

02:12 If you’re creating a sandbox script, the first thing you should do is double-check what tool marimo wants to use for package management. To do that, click Settings, then User settings,

02:24 then Package Management. And note the dropdown. Double-check that uv is selected. On older versions of marimo, you had to do this explicitly. On newer versions, it defaults to uv properly, but it doesn’t hurt to double-check it.

02:41 Also, see the little note on the bottom here where sandboxing mode currently only works with uv. Let me close this out. Click off the dialog box to close this one. I’d prefer a nice obvious giant X, but hey, what are you going to do?

02:57 And now over here on the left, click the cube icon to manage the packages.

03:02 If I open this up, you see all the things that come with marimo.

03:08 You could use the prompt here to explicitly install something, but instead, I’m going to go over to the cell and paste in some code.

03:19 This code creates a simple pandas DataFrame. This last line here is kind of like evaluating the language’s variable in the REPL. You type it in, and you get a response.

03:30 marimo will display its contents in a table instead, though. Let me run this.

03:36 Since I’m in sandboxing mode, marimo detects that pandas isn’t installed and offers to use uv to fix that for me. I’ll click install,

03:47 and as I’ve installed pandas before with uv, it’s cached. So that happened pretty quickly. It paused for a second, then refreshed, and now it’s displaying the DataFrame as a table.

03:57 Pretty sweet, huh? The best part of this is the dependency is associated with the notebook. If I sent you my file and you also used the sandbox flag, the dependencies would get installed automatically.

04:10 Let’s take a quick peek at the underlying Python file to see just how that is accomplished.

04:17 This is packages.py, the notebook I just created. Up at the top here is a special comment that includes the script’s dependency information.

04:25 This isn’t a marimo thing, but a relatively recent addition to the Python packaging standard. Many of your favorite packaging tools, uv included, know how to process the directive in this comment.

04:38 So nothing marimo specific here. marimo’s just taking advantage of this feature. For more information on how this kind of directive works, see PEP 723 that defined it.

04:51 In addition to sandboxing making it easier to send your notebook to someone else, you can also export your notebook as a regular old Python file. I’ll show you how to do that next.