prime-4

A short intro to UV and Marimo for more reproducible research!

UV

UV is a package, python version and project manager for Python written in Rust, you can install it with:

curl -LsSf https://astral.sh/uv/install.sh | sh

You should always take a look at scripts before running them from the internet!

Starting a Project

To create a new project with UV simply run

uv init projectname

Migrating an existing project is generally straightforward as well.

If you are using a Requirement.txt simply run:

cd projectdir
uv init
uv add -r Requirements.txt

If you are using venv and have not created the Requirements.txt do so like this:

First activate your virtual environment as you usually do, e.g.

cd projectdir
# UNIX-like
source venv/bin/activate 

# Windows
venv\Scripts\activate

Then you write your dependencies to the Requirements.txt

pip freeze > Requirements.txt
deactivate

Now add them to the uv project as explained before. If you are installing all of your packages globally or use another tool like poetry you are beyond my help!

Adding dependencies

UV makes this very simple, in the spirit of this little write-up let us add Marimo and some other ML tooling:

uv add marimo pandas matplotlib numpy

Now UV will resolve your dependencies and then create a Pyproject.toml containing this information, which you may manually edit to specify additional features and such!

Running your code

When pulling your repo on a new machine UV will manage everything for you, to run a script simply run:

uv run main.py

and uv will create virtual environments as needed and install your dependencies as specified.

To run a tool command (like starting a Marimo notebook), simply run:

uv run marimo edit

And More

UV has many other great features, like dev dependencies which are not shipped when publishing your code as a package etc. but you can learn all about this at the official website.

Marimo

Marimo is Jupyter Notebook alternative with a focus on reproducibility. No more running cells in various orders and producing different results for the same input each time. An additional benefit is that it plays nice with Git, no more garbled JSON files messing up your commits.

Getting Started

If you are already using UV simply install and run Marimo in your project like this:

uv add marimo
uv run marimo edit

A browser window will open and you are done. You never have to think about creating Kernels again!

If you're familiar with Jupyter this should all be quite familiar to you, if you feel stuck I recommend that you consult the docs.