Using uv¶
uv is an extremely fast Python package and project manager: you can use it to install packages, manage the dependencies of Python projects, and run scripts. While marimo supports all major package managers, it integrates especially tightly with uv. In particular, marimo's package sandbox feature, which lets you inline dependencies in notebook files, requires uv.
No prior knowledge required
This guide teaches you the basics of using uv
with marimo. It assumes zero
familiarity with uv
.
You can manage your notebooks' dependencies in three different ways:
- inline dependencies: inlining dependencies in notebook files, using
marimo edit --sandbox notebook.py
- projects: using a
uv
project , which define dependencies declaratively in apyproject.toml
file; - non-project environment: dependencies are imperatively installed
We'll walk through each of these three ways in this guide.
Using inline dependencies¶
The easiest way to get started is to use marimo's package sandbox
feature, which manages your dependencies for you.
Create or edit your notebook with uvx
command,
making sure to include the --sandbox
flag:
This command installs marimo in a temporary environment, activates it, then
runs your marimo notebook. The --sandbox
flag what tells marimo to keep
track of your dependencies and store them in the notebook file. If there are
any dependencies already tracked in the file, this command will download
them and install them in the environment.
Run sandboxed notebooks as scripts with
From URLs¶
You can also upload sandboxed notebooks to the web, such as on GitHub, and have others run them locally with a single command:
uvx marimo edit --sandbox https://gist.githubusercontent.com/kolibril13/a59135dd0973b97d488ba21c650667fe/raw/5f98021b5d3c024d5827fa9464787517495178b4/marimo_minimal_numpy_example.py
Note:
- This command will run code from a URL. Make sure you trust the source before proceeding.
- Upon execution, you’ll be prompted:
To proceed securely, ensure you have Docker installed and running, then press
Y
.
To learn more, read our full guide on using inline dependencies.
Using uv projects¶
A uv
project is a directory in which you can store Python code, including
notebooks, alongside a pyproject.toml file that declares the project's
dependencies.
Creating a project¶
Create a project with uv init
:
Starter template
Get started quickly by cloning our starter template.
This creates a pyproject.toml and some starter code.
Next, add marimo to your project:
Omitting marimo from your project
Adding marimo to your project is optional. Instead, you can
run marimo in a temporary environment that has access to
your project's dependencies using uv run --with marimo marimo edit
.
Running marimo¶
Once you've added marimo, use the uv run
command
to run the version of marimo installed in your project:
Starting marimo in this way will let marimo import any of the packages installed in your project.
Scripts. Run marimo notebooks as scripts with
which will run your notebook in an environment containing your project dependencies.
Adding and removing dependencies¶
Using the uv command-line¶
Use uv add
to add dependencies:
You can also specify a version
Remove packages with uv remove
:
Using the marimo editor¶
If you started marimo with uv run marimo edit
, the marimo editor's package
management features will add and remove packages from
your pyproject.toml, so there's no need to use the uv
command-line if you
don't want to.
Using marimo in a non-project environment¶
If you are used to a venv and pip based workflow, you can use the uv venv
and
uv pip
commands for a similar but more performant experience:
uv venv
creates a virtual environment in the current directory, at.venv
uv pip
lets you install and uninstall packages in the venv
Example¶
From here, import numpy
will work within the notebook, and marimo's UI installer will add
packages to the environment with uv pip install
on your behalf.