# How to Use marimo with uv


[marimo](https://pydevtools.com/handbook/reference/marimo.md) is a reactive Python notebook stored as a plain `.py` file, and [uv](https://pydevtools.com/handbook/reference/uv.md) 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](https://pydevtools.com/handbook/explanation/what-is-pep-723.md) 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](https://pydevtools.com/handbook/how-to/jupyter-notebook-with-uv.md).

## Prerequisites

- [uv installed](https://docs.astral.sh/uv/getting-started/installation/) and on your `PATH`
- Familiarity with running notebooks

## Pin a notebook's dependencies with `--sandbox`

Open or create a sandboxed notebook in one command:

```bash
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`:

```bash
uv add --script analysis.py marimo numpy
```

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

```python {filename="analysis.py"}
# /// 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:

```bash
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:

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

> [!IMPORTANT]
> `uv run notebook.py` works only when `marimo` is listed in the notebook's dependencies. A notebook sandboxed through marimo's UI tracks the packages you import, but you still need `marimo` in the block for standalone execution. Add it with `uv add --script notebook.py marimo`.

## Open a quick notebook without a sandbox

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

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

[uvx](https://pydevtools.com/handbook/reference/uvx.md) 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:

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

The notebook shares the project's locked [virtual environment](https://pydevtools.com/handbook/explanation/what-is-a-virtual-environment.md), 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:

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

> [!WARNING]
> Packages you install from marimo's UI in `--with` mode are not written to your project and may disappear on the next launch. Use `uv add` to persist them, or `--sandbox` to store them in the notebook file.

## Learn more

- [Using uv with marimo](https://docs.astral.sh/uv/guides/integration/marimo/) is uv's integration guide.
- [Using uv](https://docs.marimo.io/guides/package_management/using_uv/) is marimo's own guide to the same modes.
- [How to write self-contained Python scripts using PEP 723 inline metadata](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script.md) explains the metadata block sandbox mode relies on.