marimo+uv workflow

Question

I just tried uv run --python 3.11 --with marimo --with numpy --with matplotlib marimo edit --sandbox hi.py the equivalent pattern for jupyterlab would beuv run --python 3.13 --with jupyterlab --with numpy --with matplotlib jupyter labbut now I'm wondering:When I start the marimo notebook notebook, why are the packages not installed? Currently I get the error: The following packages were not found: "matplotlib" , "numpy" (see screenshot)

Myles Scolnick · Answer

does it work if you use --with-requirements (and a req.txt) instead of --with?

Myles Scolnick · Answer

maybe a formatting issue with the --with command

Jan-Hendrik Müller · Answer

just triedecho "pandas" > requirements.txt
uv run --with marimo --with-requirements "requirements.txt" marimo edit --sandbox hi.pybut that did not work as well.I also could not find the --with-requirements anywhere in the docs https://marimo.io/blog/sandboxed-notebooks , https://docs.astral.sh/uv/concepts/tools/#including-additional-dependencies

Jan-Hendrik Müller · Answer

Jan-Hendrik Müller · Answer

Here's a workaround that does work:uv add --script hi.py pandas matplotlib numpy uv run --with marimo marimo edit --sandbox hi.py

Jan-Hendrik Müller · Answer

Myles Scolnick · Answer

I wouldn’t chain “with” commands. That seems like an anti pattern and fragile

Myles Scolnick · Answer

And honestly, I wouldn’t use uv directly and instead just use “marimo edit —sandbox”. I think it complicates it

Myles Scolnick · Answer

—sandbox does for you what it looks like you are trying to achieve yourself, and hides away uv

Jan-Hendrik Müller · Answer

That makes sense! But I don't have a global installation of marimo.So I guess uvx marimo edit --sandbox hi.py would be the way to go then?

Myles Scolnick · Answer

That works - curious why not globally install it? It’ll save you 4 keystrokes each time

Jan-Hendrik Müller · Answer

how do I install marimo globally?

Myles Scolnick · Answer

This is the correct way in my opinion (I’m no uv expert) to use uv if you don’t want to install it globally

Myles Scolnick · Answer

Uv has a concept of tools - you can do “uv tool install marimo”. But that sits in its own venv - so I would only do that if you exclusively use sandbox

Jan-Hendrik Müller · Answer

I see! And would that be locked to a specific python version?

Jan-Hendrik Müller · Answer

Myles Scolnick · Answer

lol it says the fix right there

Myles Scolnick · Answer

Read closely

Jan-Hendrik Müller · Answer

yep, it's uv tool update-shell

Jan-Hendrik Müller · Answer

Jan-Hendrik Müller · Answer

just pasting the screenshot for documentation reasons, so that other members/LLMS can see the whole process.

Jan-Hendrik Müller · Answer

and e.g. when I now want to use python 3.11, would that be also possible?

Myles Scolnick · Answer

good idea

Akshay · Answer

That's a good question. I'm not sure if uv tool / uvx (uvx is a shorthand for uv tool) supports having multiple installations of the tool across multiple Python versions. Your feedback and experiments are helpful, we're still learning best practices of how to use uv

Jan-Hendrik Müller · Answer

small correction: accroding to their docs, uvx is a shorthand for uv tool run: https://docs.astral.sh/uv/concepts/tools/#the-uv-tool-interface

Jan-Hendrik Müller · Answer

and next question: I just ran marimovia uvx marimo edit --sandbox marimo_uv.py and I get the message ther there's an update available to marimo 0.9.8.The terminal suggests me to usepip install marimo, but I guess it will be uv pip install --upgrade marimo ?Or should it be uv tool install marimo --upgrade?

Jan-Hendrik Müller · Answer

I tried uv tool install marimo --upgrade now and that worked great 🍀

Jan-Hendrik Müller · Answer

just cross-posted this question in the Astral discord: https://discord.com/channels/1039017663004942429/1039017663512449056/1295033037578440736

Jan-Hendrik Müller · Answer

some inputs on this from their discord

Myles Scolnick · Answer

Yea thats correct - we call uv run ourselves

Jan-Hendrik Müller · Answer

Jan-Hendrik Müller · Answer

(second cross-post of the answer)

Jan-Hendrik Müller · Answer

I see! So in theory, the --python 3.11 flag could be called as well in that context?

Myles Scolnick · Answer

We could pass the python flag to uv in our cli args. Can you specify this with an environment variable?

Jan-Hendrik Müller · Answer

Can you specific this with an environment variable? II dont understand, can you explain this a bit more?

Myles Scolnick · Answer

Sorry typo: specify Can you set the python version using an env variable

Jan-Hendrik Müller · Answer

Thanks for rephrasing, but I think I still don't understand the idea

Akshay · Answer

The suggestion is to set UV_PYTHON=python3.11 instead of using the CLI flag: https://docs.astral.sh/uv/configuration/environment/

Jan-Hendrik Müller · Answer

hey @Akshay , thanks for the suggestion!
Indeed, prepending the environment variable to the command does work 🎉
in my zsh shell im Mac I can install
UV_PYTHON=python3.11 uv tool install marimo
and then run
marimo edit hi.py
and it will run python3.11.

Similar I can run
UV_PYTHON=python3.13 uv tool install marimo
and then run
marimo edit hi.py to use python3.13
(screenshot for reference)

Akshay · Answer

Fantastic!

Akshay · Answer

For a one liner, you can even do the following:UV_PYTHON=python3.13 uvx marimo edit hi.py

Jan-Hendrik Müller · Answer

Awesome! But that I can also do with uvx --python 3.13 marimo edit hi.py , wich is maybe a bit cleaner.But is uvx --python 3.13 marimo edit hi.py
and
UV_PYTHON=python3.13 uvx marimo edit hi.py100% identical?

Akshay · Answer

As far as I can tell from their docs, yea

Jan-Hendrik Müller · Answer

Awesome! Figuring out all this packaging stuff is like walking through fog, exploring and never knowing if you will reach the destiny.But on the path I think I figured out some best practices that I'll use now when working with marimo, that I'll share right here.I'll have a global version of marimo installed viauv tool install marimoor with a specific python version usingUV_PYTHON=python3.11 uv tool install marimo (this will overwrite the previous global installation)Furthermore, the global version of marimo can be updated via uv tool install marimo --upgrade.When I run a script with the global marimo version, I'll do that viamarimo edit hi.py --sandbox When I run a script that already ran once with a --sandbox flag, I can simply omit this flag and run marimo edit hi.pyThe CLI tell me "This notebook has inlined package dependencies.Run in a sandboxed venv containing this notebook's dependencies? [Y/n]" and I'll press "Enter" to continueNow, when I don't want to use the global marimo, but a temporary marimo version instead, I'll run uvx marimo edit --sandbox hi.pythis line is 100% identical to uv tool run marimo edit --sandbox hi.pybecause "uvx" is an alias to "uv tool run".I can also specify a python version here, like thisuvx --python 3.13 marimo edit hi.pyThe thing about uvx marimo is the following: It's not installed, it's just cached. Runing uv cache clean will remove all artifacts from my system that were cached with uvx before.Another option is to work with a virtual environment using uv:uv venv
uv pip install marimo
uv run marimo edit hi.py this venv can also be activated via source .venv/bin/activate and then marimo can be started via marimo edit hi.py .And always, if I'm not sure what marimo installation I'm currently using, I can run which marimo and it will show me the file path.

Jan-Hendrik Müller · Answer

Finally, I can also run marimo in a project with uv like this:uv init (this will create a pyproject.toml file)
uv add marimo (this will add "marimo>=0.9.9" to dependencies in pyproject.toml)
uv run marimo edit hi.py

Akshay · Answer

Thank you for writing this up!

lucharo · Answer

Why would you use global vs non global marimo?

lucharo · Answer

Can we use global marimo with a custom venv?

lucharo · Answer

Is uv add marimo functionally different to uv pip install marimo?

Jan-Hendrik Müller · Answer

Can we use global marimo with a custom venv? I'm really interested in that question as well!

mxs · Answer

I just found this thread because I was confused what the value add of --sandboxis if one is already using uv for everything?

uv already gives you full project reproducibility with lockfiles!

Imho, installing software globally is a very bad idea (uv tool install / "why not globally install it? It’ll save you 4 keystrokes each time")
I also do not want marimo to "hide away" uv for me.

running

uv run --with marimo --with torch marimo edit

and then trying to import numpy will make marimo show the "install numpy with uv" popup, but I would like to find out what would actually happen then.

if I haven't activated the venv (not necessary anymore when you use uv run, which is the only way I interact with python these days), what does this actually do?

mxs · Answer

a simpler instance of this question would be:uv init .
uv add marimo torch
uv run marimo edit (inside marimo, make a new file, in a new cell: import numpy)what does "install with uv" do? does one need the --sandbox argument to edit? (aside: pip is selected as the default for some reason?)

Myles Scolnick · Answer

we try to auto infer what it was run with but it’s not always correct.

we also initially supported uv when it was “uv pip” and not uv add, so right now the install will just call uv pip install. instead you’d want uv add

Myles Scolnick · Answer

If you want to file a ticket, we can support “uv add”

mxs · Answer

sounds good! I can open one

mxs · Answer

any hints about the need (or lack thereof) for --sandbox ?

Myles Scolnick · Answer

That does “uv script” and treats your notebook as a standalone script with its inlined metadata. Yes, there are 3-4 ways uv can install deps

mxs · Answer

I see, so it wouldn't be what one wants for this usecase.I'm not entirely sure what the behaviour with uv runshould be (aka the first example I described)

Myles Scolnick · Answer

I think uv will install an ephemeral virtual environment, unless you are in an existing uv project. Short answer, I’m not sure but uv docs might be clearer

mxs · Answer

yes, this is exactly what uv does. my question was regarding what should marimo's dependency popup do in this case

mxs · Answer

I'll include that in the issue

Myles Scolnick · Answer

oh - it would probably be better to choose installation for the way you ran marimo, but I think it’s hard to figure it out with full confidence

mxs · Answer

created the issue: https://github.com/marimo-team/marimo/issues/3904

mxs · Answer

let me know if I should clarify anything further @Myles Scolnick

lucharo · Answer

heya, I come to this thread confused from time to time, I am trying to use marimo with python 3.11 but the uvx version doesn't get used in marimo, see:uvx --python 3.11 marimo edit --sandbox /tmp/toy.py Installed 24 packages in 148ms
Running in a sandbox: uv run --isolated --no-project --with-requirements /var/folders/kt/5fbzpd0j197d08q5bbft193m0000gn/T/tmp5f64x147.txt --python >=3.12 marimo edit /tmp/toy.py

lucharo · Answer

note --python 3.11 and then the auto-generated sandbox 3.12

lucharo · Answer

In this case I just edited the python version automatically in the notebook file

lucharo · Answer

to reproduce:uvx --python 3.11 marimo edit --sandbox /tmp/t.py # Ctrl + C
cat /tmp/t.pysee:$ uvx --python 3.11 marimo edit --sandbox /tmp/t.py 15:54:15
Running in a sandbox: uv run --isolated --no-project --with-requirements /var/folders/kt/5fbzpd0j197d08q5bbft193m0000gn/T/tmpxbb77g76.txt --refresh marimo edit /tmp/t.py
Installed 24 packages in 60ms Edit t.py in your browser :pencil: ➜ URL: http://localhost:2719?access_token=gPJZayU_EuNqQBgc81nF9Q Are you sure you want to quit? (y/n): y Thanks for using marimo! :ocean::leaves: (ml_pipelines) ➜ /Users/lucharo/Projects/ml_pipelines git:(rnd-autogluon) ✗ VPN ✓
$ cat /tmp/t.py 15:54:23
# /// script
# requires-python = ">=3.12"
# dependencies = [
# "marimo",
# ]
# ///

Akshay · Answer

The version in the sandbox file takes precedence

lucharo · Answer

There’s no sandbox in my latest snippet though? Like, I’m creating it from scratch

Akshay · Answer

Oh sorry, I misread ... hmm.

Get help from the marimo community

marimo+uv workflow