Running Marimo with uv
¶
You can run a Marimo notebook using uv
through one of the following methods:
Within a project environment
Temporary installation (cached)
Directly from a URL
Using
uv
as a globally installed tool
Running in a Project Environment¶
We recommend running Marimo within a project-specific environment.
Here’s how you can set it up:
uv venv
uv pip install marimo
uv run marimo edit hi.py
The uv run
command provides the simplest way to access the virtual environment.
However, if you prefer to activate it manually, you can do so with the following commands:
source .venv/bin/activate
marimo edit hi.py
Using Specific Python Versions¶
To specify a Python version, add the --python
option while creating the venv. For example:
uv venv --python 3.13
Tip
uv will automatically fetch Python versions as needed — you don’t need to install Python to get started.
If no version is specified, the default Python version is used (currently: [TODO: Specify default Python version]).
Installing Packages¶
There are three ways to install additional packages:
Via Terminal
Run the following command:uv pip install matplotlib polars
Within the Notebook
Typeimport polars as pd
. Run the cell, and a “Missing package” pop up window will appear.
![](/_static/image.png)
Using the Packages Tab
Navigate to the “Packages” tab and select the desired package.
![](/_static/image-1.png)
Defining Dependencies with pyproject.toml
¶
A pyproject.toml file makes it easier to manage your project’s dependencies in one place. Using the uv tool, you can quickly set up and customize your project’s environment
uv init # Creates a pyproject.toml file
uv add marimo # Adds "marimo>=0.9.31" to dependencies
uv run marimo edit hi.py
Reading a pyproject.toml
from an already exisiing project.¶
Temporary installation¶
This won’t create a virtual environment folder in your working direory. Instead, uv will cache all dependencies, make a temporary venv in your system, which will be destroyed after exiting the process.
uv tool run marimo edit hi.py
this line is 100% identical to
uvx marimo edit hi.py
(uvx
is an alias for uv tool run
)
From URL¶
This pattern will run marimo from a URL.
With uv run URL
What is the word
I’m looking for a word to describe this kind of code pattern. `pip install I can run a script like this uv run https://gist.githubusercontent.com/kolibril13/f4597c16452b4b72965c8d20fe6c0978/raw/a7757d3f206d467f6e76eeea621e64b0cb92530c/benchmark.py
# globally installed tool
This is not recommended, as dependencies will be installed globally as well. #TODO:FactCheck
uv tool install marimo
Use a **specific python version** (this will overwrite the previous global installation):
UV_PYTHON=python3.11 uv tool install marimo
**Update** global version of marimo:
uv tool install marimo –upgrade.
**Uninstall**
uv tool install marimo