From 20cfc93c58fed2c30f778522d64bc86aa5cab60f Mon Sep 17 00:00:00 2001 From: Akshay Agrawal Date: Tue, 27 May 2025 16:43:43 -0700 Subject: [PATCH] docs: integration with marimo guide (#13691) ## Summary This change adds a new integration guide, on using uv with marimo notebooks. It is similar to but simpler than the existing Jupyter guide, since marimo stores notebooks as Python files and also integrates tightly with uv for package management. The guide showcases four ways of using uv with marimo: 1. marimo as a standalone tool (`uvx`) 2. managing inline script metadata (an alternative to Jupyter kernels, marimo has no concept of kernels) 3. in project environments 4. in non-project environments ## Test Plan N/A as this is a docs-only change. --------- Co-authored-by: Zanie Blue --- docs/guides/integration/index.md | 3 +- docs/guides/integration/marimo.md | 108 ++++++++++++++++++++++++++++++ mkdocs.template.yml | 1 + 3 files changed, 111 insertions(+), 1 deletion(-) create mode 100644 docs/guides/integration/marimo.md diff --git a/docs/guides/integration/index.md b/docs/guides/integration/index.md index 209ec358a..c064c6db2 100644 --- a/docs/guides/integration/index.md +++ b/docs/guides/integration/index.md @@ -3,7 +3,8 @@ Learn how to integrate uv with other software: - [Using in Docker images](./docker.md) -- [Using with Jupyter](./jupyter.md) +- [Using with Jupyter notebooks](./jupyter.md) +- [Using with marimo notebooks](./marimo.md) - [Using with pre-commit](./pre-commit.md) - [Using in GitHub Actions](./github.md) - [Using in GitLab CI/CD](./gitlab.md) diff --git a/docs/guides/integration/marimo.md b/docs/guides/integration/marimo.md new file mode 100644 index 000000000..c0209d941 --- /dev/null +++ b/docs/guides/integration/marimo.md @@ -0,0 +1,108 @@ +--- +title: Using uv with marimo +description: + A complete guide to using uv with marimo notebooks for interactive computing, script execution, + and data apps. +--- + +# Using uv with marimo + +[marimo](https://github.com/marimo-team/marimo) is an open-source Python notebook that blends +interactive computing with the reproducibility and reusability of traditional software, letting you +version with Git, run as scripts, and share as apps. Because marimo notebooks are stored as pure +Python scripts, they are able to integrate tightly with uv. + +You can readily use marimo as a standalone tool, as self-contained scripts, in projects, and in +non-project environments. + +## Using marimo as a standalone tool + +For ad-hoc access to marimo notebooks, start a marimo server at any time in an isolated environment +with: + +```console +$ uvx marimo edit +``` + +Start a specific notebook with: + +```console +$ uvx marimo edit my_notebook.py +``` + +## Using marimo with inline script metadata + +Because marimo notebooks are stored as Python scripts, they can encapsulate their own dependencies +using inline script metadata, via uv's [support for scripts](../../guides/scripts.md). For example, +to add `numpy` as a dependency to your notebook, use this command: + +```console +$ uv add --script my_notebook.py numpy +``` + +To interactively edit a notebook containing inline script metadata, use: + +```console +$ uvx marimo edit --sandbox my_notebook.py +``` + +marimo will automatically use uv to start your notebook in an isolated virtual environment with your +script's dependencies. Packages installed from the marimo UI will automatically be added to the +notebook's script metadata. + +You can optionally run these notebooks as Python scripts, without opening an interactive session: + +```console +$ uv run my_notebook.py +``` + +## Using marimo within a project + +If you're working within a [project](../../concepts/projects/index.md), you can start a marimo +notebook with access to the project's virtual environment via the following command (assuming marimo +is a project dependency): + +```console +$ uv run marimo edit my_notebook.py +``` + +To make additional packages available to your notebook, either add them to your project with +`uv add`, or use marimo's built-in package installation UI, which will invoke `uv add` on your +behalf. + +If marimo is not a project dependency, you can still run a notebook with the following command: + +```console +$ uv run --with marimo marimo edit my_notebook.py +``` + +This will let you import your project's modules while editing your notebook. However, packages +installed via marimo's UI when running in this way will not be added to your project, and may +disappear on subsequent marimo invocations. + +## Using marimo in a non-project environment + +To run marimo in a virtual environment that isn't associated with a +[project](../../concepts/projects/index.md), add marimo to the environment directly: + +```console +$ uv venv +$ uv pip install numpy +$ uv pip install marimo +$ uv run marimo edit +``` + +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. + +## Running marimo notebooks as scripts + +Regardless of how your dependencies are managed (with inline script metadata, within a project, or +with a non-project environment), you can run marimo notebooks as scripts with: + +```console +$ uv run my_notebook.py +``` + +This executes your notebook as a Python script, without opening an interactive session in your +browser. diff --git a/mkdocs.template.yml b/mkdocs.template.yml index 8f00d782b..dea9496cf 100644 --- a/mkdocs.template.yml +++ b/mkdocs.template.yml @@ -109,6 +109,7 @@ nav: - guides/integration/index.md - Docker: guides/integration/docker.md - Jupyter: guides/integration/jupyter.md + - marimo: guides/integration/marimo.md - GitHub Actions: guides/integration/github.md - GitLab CI/CD: guides/integration/gitlab.md - Pre-commit: guides/integration/pre-commit.md