How to Use marimo with uv

marimo is a reactive Python notebook stored as a plain .py file, and uv is its recommended package manager. What sets the pairing apart is the sandboxed notebook: a marimo file that declares its own dependencies in a PEP 723 inline metadata block and recreates its environment from those declared dependencies on any machine through uv.

This guide covers three ways to run marimo with uv: sandboxed notebooks that carry their own dependencies for portable files, ad-hoc sessions for throwaway work, and project environments that share a locked set of dependencies. For classic Jupyter notebooks, see How to Run a Jupyter Notebook with uv.

Prerequisites

• uv installed and on your PATH
• Familiarity with running notebooks

Pin a notebook’s dependencies with --sandbox

Open or create a sandboxed notebook in one command:

uvx marimo edit --sandbox analysis.py

marimo builds an isolated environment with uv and tracks the notebook’s dependencies in a PEP 723 block. Packages you install through marimo’s UI are written back into that block. The --sandbox flag reads dependencies already declared in the file and installs them automatically on launch.

To declare dependencies before opening the editor, use uv add --script:

uv add --script analysis.py marimo numpy

This writes the metadata block at the top of the file:

# /// script
# requires-python = ">=3.13"
# dependencies = [
#     "marimo",
#     "numpy",
# ]
# ///

uv fills requires-python from your active Python and adds each package to the block. List marimo itself so the notebook runs as a standalone script.

Run a sandboxed notebook anywhere with uv run

Once the notebook declares its dependencies, run it as a script:

uv run analysis.py

uv builds the environment from the inline metadata and runs the cells in dependency order, with no browser. Anything the cells print goes to your terminal:

$ uv run analysis.py
Installed 25 packages in 755ms
sum= 10

Open a quick notebook without a sandbox

For throwaway exploration, start marimo in an isolated environment with no project and no metadata block:

uvx marimo edit          # empty notebook in a fresh server
uvx marimo edit scratch.py

uvx runs marimo in an isolated environment without adding it to your project. Nothing pins the dependency versions, so reach for --sandbox once a notebook is worth keeping.

Add marimo to a uv project

When a notebook belongs to a project, add marimo as a dependency:

uv add marimo
uv run marimo edit notebooks/analysis.py

The notebook shares the project’s locked virtual environment, so it imports your project’s own modules. Add new packages with uv add, or through marimo’s package manager panel, which writes project dependencies back to pyproject.toml when marimo runs inside a uv project.

To run marimo for one session without adding it to the project:

uv run --with marimo marimo edit notebooks/analysis.py

Learn more

• Using uv with marimo is uv’s integration guide.
• Using uv is marimo’s own guide to the same modes.
• How to write self-contained Python scripts using PEP 723 inline metadata explains the metadata block sandbox mode relies on.