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