A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
Reframe package management docs around projects and sandboxes (#10940)
Trevor Manze8d93e897ebf
diff --git a/.github/workflows/test_be.yaml b/.github/workflows/test_be.yamlindex dc70fdb050..a1b0f46a0b 100644--- a/.github/workflows/test_be.yaml+++ b/.github/workflows/test_be.yaml@@ -43,6 +43,8 @@ jobs:steps:- name: ⬇️ Checkout repouses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4+ with:+ fetch-depth: 0- name: 🐍 Setup uvuses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7diff --git a/docs/faq.md b/docs/faq.mdindex 9c2b0474a1..97bef49da2 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -49,9 +49,9 @@ consistent, eliminating hidden state and making your notebook reproducible.marimo achieves this by intelligently analyzing your code and understanding therelationships between cells, and automatically re-running cells as needed.-In addition, marimo notebooks can serialize package requirements inline;-marimo runs these "sandboxed" notebooks in temporary virtual environments,-making them [reproducible down to the packages](guides/editor_features/package_management.md).+In addition, marimo notebooks can [carry their package requirements](guides/package_management/sandboxes.md)+inside the notebook file. marimo runs these notebooks in separate environments,+and script lockfiles can record resolved dependency versions for sharing.**Maintainability.**marimo notebooks are stored as pure Python programs (`.py` files). This lets youdiff --git a/docs/getting_started/installation.md b/docs/getting_started/installation.mdindex 8573d32249..5650a30dfa 100644--- a/docs/getting_started/installation.md+++ b/docs/getting_started/installation.md@@ -1,45 +1,46 @@----description: "Install marimo with pip, uv, or conda. Set up a virtual environment and get started with the reactive Python notebook."+description: "Install marimo with pip, uv, Pixi, or conda. Use a project manager or set up your own environment to get started."---# Installation-Before installing marimo, we recommend creating and activating a Python-[virtual environment](https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments).+You can install marimo alongside your notebook's packages using any major Python+package manager. With pip or Conda, you'll first need to create and activate a+[virtual environment](../guides/package_management/projects.md#use-an-existing-environment)+or [Conda+environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-with-commands).+Project managers such as uv and Pixi handle this setup automatically when you+launch marimo from your project with `uv run` or `pixi run`.-??? note "Setting up a virtual environment"+//// admonition | Try a standalone notebook+ type: tip- Python uses virtual environments to minimize conflicts among packages.- Here's a quickstart for `pip` users. If you use `conda`, please use a [`conda`- environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-with-commands)- instead.+[uv](https://docs.astral.sh/uv/) and [Pixi](https://pixi.prefix.dev/) can manage+Python and install marimo for you without setting up a project. To try a notebook+with its own dependencies:- Run the following in the terminal:+/// tab | uv- - create an environment with `python -m venv marimo-env`- - activate the environment:- - macOS/Unix: `source marimo-env/bin/activate`- - Windows: `marimo-env\Scripts\activate`+```bash+uvx marimo edit --sandbox notebook.py+```- _Make sure the environment is activated before installing marimo and when- using marimo._ Install other packages you may need, such as numpy, pandas, matplotlib,- and altair, in this environment. When you're done, deactivate the environment- with `deactivate` in the terminal.+///- Learn more from the [official Python tutorial](https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments).+/// tab | Pixi-/// admonition | Using uv?- type: tip+```bash+pixi exec marimo edit --sandbox=pixi notebook.py+```-[uv](https://docs.astral.sh/uv/) is a next-generation Python package-installer and manager that is 10-100x faster than pip, and also makes it easy-to install Python and manage projects. Create a [uv-project](https://docs.astral.sh/uv/guides/projects/) with `uv init`; this-creates and manages a virtual environment for you behind-the-scenes. For-detailed information on using marimo with `uv`, see our [uv-guide](../guides/package_management/using_uv.md).///+To add marimo to an existing codebase, see+[working in projects](../guides/package_management/projects.md).+See [package management](../guides/package_management/index.md) to compare+projects and notebook sandboxes.+////+/// admonition | Use our editor extensionstype: tip@@ -71,6 +72,8 @@ marimo tutorial intro/// tab | install with uv+From your project directory (run `uv init` first for a new project):+```bashuv add marimo```@@ -83,6 +86,22 @@ uv run marimo tutorial intro///+/// tab | install with Pixi++From your project directory (run `pixi init --format pyproject` first for a new project):++```bash+pixi add --pypi marimo+```++To check if the install worked, run++```bash+pixi run marimo tutorial intro+```++///+/// tab | install with conda```bashdiff --git a/docs/guides/coming_from/jupyter.md b/docs/guides/coming_from/jupyter.mdindex 8de416c9f3..300e854634 100644--- a/docs/guides/coming_from/jupyter.md+++ b/docs/guides/coming_from/jupyter.md@@ -229,7 +229,7 @@ subprocess.run(["ls", "-l"])| %autoreload | marimo's [module autoreloader](../editor_features/module_autoreloading.md) || %matplotlib | marimo auto-displays plots || %pwd | `os.getcwd()` |-| %pip | Use marimo's [built-in package management](../editor_features/package_management.md) |+| %pip | Use marimo's [built-in package management](../package_management/installing_packages.md) || %who_ls | `dir()`, `globals()`, [`mo.refs()`][marimo.refs], [`mo.defs()`][marimo.defs] || %system | `subprocess.run()` || %%time | `time.perf_counter()` or Python's timeit module |@@ -243,7 +243,7 @@ subprocess.run(["ls", "-l"])Use marimo's package management sidebar panel to install packages to your currentenvironment. Learn more in our [package management-guide](../editor_features/package_management.md).+guide](../package_management/installing_packages.md).## Interactive guidediff --git a/docs/guides/configuration/index.md b/docs/guides/configuration/index.mdindex 68e2322d0e..a471536406 100644--- a/docs/guides/configuration/index.md+++ b/docs/guides/configuration/index.md@@ -40,7 +40,7 @@ You can customize the following settings:- Completion (auto-completion, AI copilot, etc.)- Display (theme, font size, output placement, etc.)- Autosave-- [Package management](../editor_features/package_management.md#package-management)+- [Package management](../package_management/installing_packages.md)- Server settings- [VIM keybindings](../editor_features/overview.md#vim-keybindings)- Formatting settingsdiff --git a/docs/guides/configuration/runtime_configuration.md b/docs/guides/configuration/runtime_configuration.mdindex 4881920e9a..146d96a806 100644--- a/docs/guides/configuration/runtime_configuration.md+++ b/docs/guides/configuration/runtime_configuration.md@@ -124,7 +124,7 @@ pythonpath = ["project/src"]consider configuring [uv workspaces](https://docs.astral.sh/uv/concepts/projects/workspaces/).See our guide on [notebooks in existing- projects](../package_management/notebooks_in_projects.md) for more details.+ projects](../package_management/projects.md) for more details.## Environment variablesdiff --git a/docs/guides/deploying/deploying_kubernetes.md b/docs/guides/deploying/deploying_kubernetes.mdindex 6ddfc5c260..f152f22252 100644--- a/docs/guides/deploying/deploying_kubernetes.md+++ b/docs/guides/deploying/deploying_kubernetes.md@@ -243,4 +243,4 @@ kubectl delete marimo my-notebook- [marimo-operator on GitHub](https://github.com/marimo-team/marimo-operator)- [SkyPilot deployment](./deploying_skypilot.md) - For multi-cloud VM deployment without Kubernetes- [Docker deployment](./deploying_docker.md) - For container basics-- [Inlining dependencies](../package_management/inlining_dependencies.md) - For reproducible notebooks+- [Inlining dependencies](../package_management/sandboxes.md) - For reproducible notebooksdiff --git a/docs/guides/deploying/deploying_skypilot.md b/docs/guides/deploying/deploying_skypilot.mdindex aba42c412d..1d5a694424 100644--- a/docs/guides/deploying/deploying_skypilot.md+++ b/docs/guides/deploying/deploying_skypilot.md@@ -45,7 +45,7 @@ uvx marimo edit --sandbox demo.py --port 8080 --token-password=supersecret```!!! note "Sandboxed environments"- The `uvx` command runs marimo without installing it in your environment, and the `--sandbox` flag ensures that notebook dependencies are installed in a separate environment. This makes your development fully reproducible and isolated. See [inlining dependencies](../package_management/inlining_dependencies.md) for more on creating reproducible notebooks.+ The `uvx` command runs marimo without installing it in your environment, and the `--sandbox` flag ensures that notebook dependencies are installed in a separate environment. This makes your development fully reproducible and isolated. See [inlining dependencies](../package_management/sandboxes.md) for more on creating reproducible notebooks.You can now access your marimo notebook at `localhost:8080` in your local browser and authenticate with the password you set.diff --git a/docs/guides/deploying/deploying_slurm.md b/docs/guides/deploying/deploying_slurm.mdindex 04f4048c41..ec66e2e071 100644--- a/docs/guides/deploying/deploying_slurm.md+++ b/docs/guides/deploying/deploying_slurm.md@@ -128,7 +128,7 @@ python notebook.py## Inlining configuration in notebook filesYou can inline SBATCH directives in your notebook file. If used alongside marimo's support for-[inlining package dependencies](../package_management/inlining_dependencies.md) ("sandboxing"),+[inlining package dependencies](../package_management/sandboxes.md) ("sandboxing"),this lets you create fully self-contained notebooks./// tab | Interactive developmentdiff --git a/docs/guides/editor_features/home.md b/docs/guides/editor_features/home.mdindex d8d7b9f5c1..1b77b7bd8c 100644--- a/docs/guides/editor_features/home.md+++ b/docs/guides/editor_features/home.md@@ -21,32 +21,24 @@ The home page shows all marimo notebooks in the directory, letting you:## Sandboxed Home-You can run the home page in sandbox mode (called "Sandboxed Home"), where-each notebook gets its own isolated environment:+You can open a directory in sandbox mode, giving each notebook its own isolated+environment:-```bash-marimo edit --sandbox folder/-```--When using Sandboxed Home:+=== "uv"-1. Each notebook runs in its own isolated environment-2. Dependencies are read from each notebook's [inline script metadata](../package_management/inlining_dependencies.md) (PEP 723)-3. Environments are created on-demand when you open a notebook--This is useful when you have a collection of notebooks with different-dependencies and want to keep them isolated from each other.--!!! note "Additional dependencies required"+ ```bash+ marimo edit --sandbox folder/+ ```- Sandboxed Home requires additional packages:+=== "Pixi"```bash- uv add 'marimo[sandbox]'+ marimo edit --sandbox=pixi folder/```- This installs `pyzmq` (for inter-process communication) and `uv`- (for environment management).+Each environment is prepared from the notebook's requirements when you open it.+See [working in sandboxes](../package_management/sandboxes.md#open-a-directory-of-notebooks)+for setup with uv or Pixi.### Using custom virtual environments@@ -62,16 +54,11 @@ This is configured using `[tool.marimo.venv]` in your script metadata:# ///```-!!! note "Sandboxed Home only"-- The `[tool.marimo.venv]` configuration only applies when using- Sandboxed Home (`marimo edit --sandbox folder/`). For single notebooks,- activate your virtual environment before running marimo:-- ```bash- source path/to/venv/bin/activate- marimo edit notebook.py- ```+This configuration also applies when editing a single file with+`marimo edit --sandbox notebook.py`. The configured environment takes precedence+over creating an environment from inline requirements. To use an activated+environment directly, see+[using an existing environment](../package_management/projects.md#use-an-existing-environment).#### Configuration optionsdiff --git a/docs/guides/editor_features/index.md b/docs/guides/editor_features/index.mdindex a7264f5f4b..7b4150e461 100644--- a/docs/guides/editor_features/index.md+++ b/docs/guides/editor_features/index.md@@ -10,7 +10,7 @@ with code and data.| [Overview](overview.md) | An overview of editor features and configuration || [Sidebar and Developer Panel](panels.md) | Customize your workspace with panels || [Understanding dataflow](dataflow.md) | Visualize and navigate cell dependencies |-| [Package Management](package_management.md) | Using package managers in marimo |+| [Installing packages](../package_management/installing_packages.md) | Using package managers in marimo || [AI Completion](ai_completion.md) | Code with the help of a language model || [Language Server](language_server.md) | Code intelligence via LSP || [Hotkeys](hotkeys.md) | Our hotkeys |diff --git a/docs/guides/editor_features/package_management.md b/docs/guides/editor_features/package_management.mddeleted file mode 100644index de475ce38d..0000000000--- a/docs/guides/editor_features/package_management.md+++ /dev/null@@ -1,20 +0,0 @@-# Package management--marimo supports package management for `pip`, `uv`, `poetry`, `pixi`, and-`rye`. When marimo comes across a module that is not installed, you will be-prompted to install it using your preferred package manager.--Once the module is installed, all cells that depend on the module will be rerun.--!!! note "Package Installation"-- We use some heuristic for guessing the package name in your registry (e.g. PyPI) from the module name. It is possible that the package name is different from the module name. If you encounter an error, please file an issue or help us by adding your mapping [directly to the codebase](https://github.com/marimo-team/marimo/blob/main/marimo/_runtime/packages/module_name_to_pypi_name.py).--## Package reproducibility--marimo is the only Python notebook that is reproducible down to the packages-they use. This makes it possible to share standalone notebooks without shipping-`requirements.txt` files alongside them, and guarantees your notebooks will-work weeks, months, even years into the future.--To learn more, see the [package reproducibility guide](../package_management/inlining_dependencies.md).diff --git a/docs/guides/editor_features/watching.md b/docs/guides/editor_features/watching.mdindex 4e34339f91..1f8869ca4b 100644--- a/docs/guides/editor_features/watching.md+++ b/docs/guides/editor_features/watching.md@@ -149,7 +149,7 @@ at the command-line, or rename your file to have an `.md` extension in the notebmarimo conforms to standard markdown document format, and will render mostplaces like Github. Metadata in this file format is saved in the frontmatter,which marimo may use for information like-[sandboxing](../package_management/inlining_dependencies.md), and the marimo version. All other+[sandboxing](../package_management/sandboxes.md), and the marimo version. All otherfields are kept, but ignored.For execution, marimo extracts code fences that contain `marimo` in braces. Fordiff --git a/docs/guides/exporting/webassembly_html.md b/docs/guides/exporting/webassembly_html.mdindex f781492e8f..b1c808fa39 100644--- a/docs/guides/exporting/webassembly_html.md+++ b/docs/guides/exporting/webassembly_html.md@@ -298,7 +298,7 @@ For local modules outside the notebook directory, configurecan resolve the import.If you already build a local wheel, reference it from the notebook's-[inline script metadata](../package_management/inlining_dependencies.md):+[inline script metadata](../package_management/sandboxes.md):```python# /// scriptdiff --git a/docs/guides/index.md b/docs/guides/index.mdindex 94805bc072..74752fcac7 100644--- a/docs/guides/index.md+++ b/docs/guides/index.md@@ -21,7 +21,7 @@ These guides cover marimo's core concepts.| [Understanding errors](understanding_errors/index.md) | Understanding marimo's constraints on notebook code || [Lint rules](lint_rules/index.md) | Comprehensive linting system and rule reference || [Working with data](working_with_data/index.md) | Using SQL cells, no-code dataframe, and reactive plots |-| [Package management](package_management/index.md) | Inlining dependencies in notebook files and other package management guides |+| [Package management](package_management/index.md) | Managing packages for projects and standalone notebooks || [Generate with AI](generate_with_ai/index.md) | Generate notebooks with AI || [Editor features](editor_features/index.md) | View variables, dataframe schemas, docstrings, and more || [Using your own editor](editor_features/watching.md) | Edit notebooks in your own editor and stream changes back to the browser |diff --git a/docs/guides/molab.md b/docs/guides/molab.mdindex 15ee265c54..8cf252f9d9 100644--- a/docs/guides/molab.md+++ b/docs/guides/molab.md@@ -206,7 +206,7 @@ This yields a snippet like the one below:Embedded notebooks run in the browser via WebAssembly, so your notebook must be[WebAssembly-compatible](wasm.md). We also recommend creating these notebooks-[with `--sandbox`](package_management/inlining_dependencies.md) to make sure+[with `--sandbox`](package_management/sandboxes.md) to make suretheir dependencies get installed.diff --git a/docs/guides/package_management/importing_local_code.md b/docs/guides/package_management/importing_local_code.mdnew file mode 100644index 0000000000..efe0779497--- /dev/null+++ b/docs/guides/package_management/importing_local_code.md@@ -0,0 +1,79 @@+# Importing local code++Importing local Python code lets you reuse functions and classes across+notebooks. How you make the code available depends on where the files live+and whether the code is packaged.++## Import from the notebook's directory { #importing-local-modules }++Python files alongside a notebook can be imported directly:++```text+.+├── my_notebook.py+└── my_module.py+```++In a cell of `my_notebook.py`:++```python+import my_module+```++## Import from a source directory { #from-non-package-projects }++If notebooks and source code live in separate directories, tell marimo where+to find your modules. For example, a project might keep its code in `src/`:++```text+.+├── notebooks+│ └── my_notebook.py+├── pyproject.toml+└── src+ └── my_module.py+```++Add `src` to marimo's Python search path in `pyproject.toml`:++```toml title="pyproject.toml"+[tool.marimo.runtime]+pythonpath = ["src"]+```++The notebook can then `import my_module`. The `pythonpath` setting applies in+the editor, when serving the notebook as an app, and when running it as a script.++## Import a local package { #from-packages }++If your code is organized as a [Python package](https://docs.python.org/3/tutorial/modules.html#packages),+install it in the notebook's environment. For example, a package named+`my_package` might have this layout:++```text+.+├── notebooks+│ └── my_notebook.py+├── pyproject.toml+└── src+ └── my_package+ ├── __init__.py+ └── my_module.py+```++Once installed, the notebook can import from the package:++```python+from my_package import my_module+```++An **editable installation** uses your source files directly, so you don't need+to reinstall the package after each change. See+[working in projects](projects.md#import-your-projects-code) for setup in a+shared environment, or [sandbox configuration](sandboxes.md#local-development-with-editable-installs)+for declaring the local package in the notebook's own requirements.++!!! tip "Picking up source changes"++ [Module autoreloading](../editor_features/module_autoreloading.md) lets+ marimo pick up changes to imported code while your notebook is open.diff --git a/docs/guides/package_management/importing_packages.md b/docs/guides/package_management/importing_packages.mddeleted file mode 100644index a70e8bd4fe..0000000000--- a/docs/guides/package_management/importing_packages.md+++ /dev/null@@ -1,187 +0,0 @@-# Importing packages--By default, marimo searches for packages in the [virtual-environment](https://docs.python.org/3/tutorial/venv.html) it was started in.-For example, if you run--```console-source /path/to/venv/bin/activate-marimo edit my_notebook.py-```--you'll be able to import packages installed in the environment you just-activated. You'll also be able to install packages into this environment using-the marimo editor's [package management UI](installing_packages.md).--!!! question "Using uv?"-- See our [uv guide](using_uv.md) for details on how to use marimo as part of- uv projects or as self-contained scripts.--## Inlining dependencies--As an alternative to manually creating and managing a virtual environment,-you can let marimo manage virtual environments for you, on a per-notebook-basis.--If you create a notebook with the `--sandbox` flag —--```console-marimo edit --sandbox my_notebook.py-```--— marimo will start your notebook in an isolated environment and keep track of-the dependencies you install from the editor. These dependencies are inlined in-the notebook file, so that the next time you run the notebook,-marimo will run it in an isolated environment with just those dependencies.--See our guide on [inlining dependencies](inlining_dependencies.md)-to learn more.--!!! question "What about kernels?"-- Unlike Jupyter, marimo does not have a concept of "kernels"; notebooks simply- use the active virtual environment.-- The main feature of kernels is to allow different notebooks to depend on- different packages, even within the same project. marimo's package sandbox- provides this functionality, while also being far simpler to use than- custom kernels.---## Importing local modules--marimo resolves imports just as Python does: by searching for packages-in the directories listed in `sys.path`. That means that in addition to the-virtual environment, marimo will search for modules in the directory in which-the notebook lives. For example, when you run--```console-marimo edit /path/to/notebook_dir/notebook.py-```--marimo will look for modules in `/path/to/notebook_dir`. However, this means-that you may need to take additional steps to import modules that live outside-this directory. What steps you take depends on whether your code is organized-as a Python package.--!!! tip "Remember: notebooks are just Python programs"-- In the examples below, notebooks are stored in a separate notebooks- directory, which is traditional. However, since marimo notebooks are just- Python modules, you can just as well include them in your `src/` directory- alongside other Python modules.---### From non-package projects--You can configure the Python path to accommodate directory structures that look like this:--```-.-├── notebooks-│ └── my_notebook.py-├── pyproject.toml-└── src- └── my_module.py-```--In particular, to make `import my_module` work when running--/// tab | edit--```console-marimo edit notebooks/my_notebook.py-```--///--/// tab | run--```console-marimo run notebooks/my_notebook.py-```--///--/// tab | script--```console-python notebooks/my_notebook.py-```--///--add the following configuration to your `pyproject.toml`:--```toml title="pyproject.toml"-[tool.marimo.runtime]-pythonpath = ["src"]-```--### From packages--!!! question "New to Python packages?"-- A [Python package](https://docs.python.org/3/tutorial/modules.html#packages) is a- way of structuring Python source files so that the collection of files can- be installed in an environment, imported using "dot" notation like- `from my_package.my_module import my_function`, and optionally uploaded- to package registries like PyPI.-- If you are new to packages, and find you need to create one, we recommend- using [uv](https://docs.astral.sh/uv/) (`uv init --package`).--A package has a directory structure like this:--```-.-├── notebooks-│ └── my_notebook.py-├── pyproject.toml-└── src- └── my_package- ├── __init__.py- └── my_module.py-```--Say `my_notebook` has a cell with--```python-from my_package import my_module-```--Provided that--/// tab | edit--```console-marimo edit notebooks/my_notebook.py-```--///--/// tab | run--```console-marimo run notebooks/my_notebook.py-```--///--/// tab | script--```console-python notebooks/my_notebook.py-```--///--is run from an environment in which your package is installed, marimo-will import `my_module` without issue.--For example, if you are using `uv`, simply run--```console-uv run --with marimo marimo edit notebooks/my_notebook.py-```diff --git a/docs/guides/package_management/index.md b/docs/guides/package_management/index.mdindex f118b94115..4e9400904c 100644--- a/docs/guides/package_management/index.md+++ b/docs/guides/package_management/index.md@@ -1,12 +1,165 @@# Package management-The following guides cover how to import, install, and otherwise manage-the Python dependencies of your notebooks.--| Guide | Description |-| ----------------------------------------------------- | ------------------------------------------------------------ |-| [Importing packages](importing_packages.md) | How marimo finds packages on import |-| [Installing packages](installing_packages.md) | Installing packages with marimo's UI |-| [Inlining dependencies](inlining_dependencies.md) | Create self-contained notebooks by inlining dependencies in notebook files |-| [Notebooks in existing projects](notebooks_in_projects.md) | Working with marimo notebooks in existing Python projects |-| [Using uv](using_uv.md) | A guide to using the uv package manager with marimo |+Notebooks often use Python packages, such as `matplotlib` or `polars`, that+must be installed before their code can run. **Package managers** handle+installing these libraries and their dependencies. marimo integrates with these+tools so you can [manage packages from the editor](installing_packages.md).++## Choosing a workflow++A notebook's **requirements** record which packages it needs and any+constraints on their versions. You can share requirements across a project or+store them inside individual notebooks.++A [project](projects.md) lets several notebooks and scripts _share_+requirements. A single configuration file (e.g., `pyproject.toml`) defines a+shared environment, so package changes apply to all notebooks within a project.++In [sandbox mode](sandboxes.md), each notebook carries its _own_ requirements+inside its file. marimo prepares a separate environment for each notebook from+those requirements and records package changes back into the notebook's file.++Both approaches can coexist in one repository. As a rule of thumb,+project-level requirements work well when you want to share the **project**+(e.g., a whole repository that others will clone), while notebook-level+requirements work well when you want to share the **notebook** (e.g., a+standalone file shared as a Gist).++## Choosing a package manager++For either workflow, a package manager prepares the environment where your+notebook runs. marimo supports [several package+managers](installing_packages.md) for projects. Notebook sandboxes require+**uv** or **Pixi**, two popular package managers that also work with projects:++- **[uv](https://docs.astral.sh/uv/)** is a Python package and project manager.+ It manages Python, environments, and packages from PyPI (the Python Package+ Index) in one tool.+- **[Pixi](https://pixi.prefix.dev/)** manages environments across languages using+ Conda and PyPI packages. Choose it if you're coming from the Conda ecosystem,+ rely on Conda packages, or need to manage dependencies beyond Python.++In general, we recommend using what your team or community uses. If you're+getting started on your own and aren't sure, uv is a good place to start.++## Working in a project++When working in a Python project, notebooks and scripts use a **shared+manifest** (a configuration file such as `pyproject.toml`) and a **shared+environment** prepared from its requirements.++Some tools also generate a **lockfile** that records the exact package versions+selected for those requirements.++For example, these two notebooks and their data-preparation script use the same+*project* requirements and environment:++=== "uv"++ ```text+ analysis/+ ├── pyproject.toml # Project manifest+ ├── uv.lock # Resolved dependency versions+ ├── prepare_data.py+ └── notebooks/+ ├── explore.py+ └── report.py+ ```++ With marimo included in the project's dependencies, open a notebook with:++ ```bash+ uv run marimo edit notebooks/explore.py+ ```++=== "Pixi"++ ```text+ analysis/+ ├── pyproject.toml # Workspace manifest+ ├── pixi.lock # Resolved dependency versions+ ├── prepare_data.py+ └── notebooks/+ ├── explore.py+ └── report.py+ ```++ Pixi calls a project a *workspace* and also supports `pixi.toml` as its manifest.++ With marimo included in the workspace's dependencies, open a notebook with:++ ```bash+ pixi run marimo edit notebooks/explore.py+ ```++Here, `uv run` and `pixi run` launch the marimo installed in the project's shared+environment. See [working in projects](projects.md) for setup with other package+managers and local development.++## Working in a sandbox++In [sandbox mode](sandboxes.md), each notebook contains its **own manifest** as inline script+metadata. marimo uses it to prepare an **isolated environment** for that+notebook, so notebooks can use different packages or versions without affecting+each other.++With uv or Pixi installed, you can open a notebook with:++=== "uv"++ ```bash+ uvx marimo edit --sandbox notebook.py+ ```++ uv is the default package manager for sandboxes and installs packages from PyPI.++=== "Pixi"++ ```bash+ pixi exec marimo edit --sandbox=pixi notebook.py+ ```++ Pixi supports Conda packages alongside PyPI packages.++[`uvx`](https://docs.astral.sh/uv/concepts/tools/) and [`pixi+exec`](https://pixi.prefix.dev/latest/reference/cli/pixi/exec/) install and+launch marimo. The `--sandbox` option tells marimo to prepare a separate+environment for the notebook's code.++Python version and package requirements are stored as **inline script metadata**+([PEP 723](https://peps.python.org/pep-0723/)) in a comment block at the top of the+notebook. The `dependencies` field lists Python packages, typically from PyPI.++```python title="notebook.py (header)"+# /// script+# requires-python = ">=3.11"+# dependencies = [+# "marimo",+# "polars",+# "altair",+# ]+# ///+```++When you install Python packages through the editor, marimo updates both the+inline metadata and the notebook's environment.++Sandboxes don't inherit the surrounding project's packages. The same block can+include [uv- or Pixi-specific metadata](sandboxes.md#backend-specific-metadata)+for local packages, other package sources, or Conda dependencies. marimo passes+these settings to the selected backend when preparing the environment.++See [working in sandboxes](sandboxes.md) for managing dependencies and sharing+notebooks with any required data or source files.++!!! note "Dependency isolation"++ A notebook sandbox isolates installed packages. It does not restrict the+ notebook's access to your files or network; only run code you trust.++## Running notebooks as scripts++The same notebook can be edited interactively or executed from the terminal.+uv and Pixi can run notebooks using either project dependencies or inline+requirements. See [running notebooks as scripts](../scripts.md) for both workflows,+command-line arguments, and scheduled jobs.diff --git a/docs/guides/package_management/inlining_dependencies.md b/docs/guides/package_management/inlining_dependencies.mddeleted file mode 100644index a68228df79..0000000000--- a/docs/guides/package_management/inlining_dependencies.md+++ /dev/null@@ -1,324 +0,0 @@-# Inlining dependencies--marimo is the only Python notebook that is reproducible down to the packages,-letting you inline Python dependencies in notebook files and running notebooks-in isolated or "sandboxed" venvs. This lets you share standalone notebooks-without shipping `requirements.txt` files alongside them, and guarantees your-notebooks will work weeks, months, even years into the future.--To opt-in to dependency inlining, use the `sandbox` flag:--=== "edit"-- ```bash- marimo edit --sandbox notebook.py- ```--=== "run"-- ```bash- marimo run --sandbox notebook.py- ```--=== "new"-- ```bash- marimo new --sandbox- ```--When running with `--sandbox`, marimo:--1. tracks the packages and versions used by your notebook, saving- them in the notebook file;-2. executes the notebook in an isolated virtual environment ("sandbox") that only- contains the notebook dependencies.--For `edit` and `new`, the editor server starts in your current Python-environment. Each notebook gets its own sandboxed kernel when you open it,-whether you start with a single file or a folder. The editor can therefore-start before the notebook's dependencies are installed. Editor features such-as language servers use packages installed alongside the server.--marimo's sandbox provides two key benefits. (1) Notebooks that carry their own-dependencies are easy to share — just send the `.py` file. (2) Isolating a-notebook from other installed packages prevents obscure bugs.--!!! tip "Sandboxed Home"-- You can also use `--sandbox` when editing a folder of notebooks. Each- notebook gets its own isolated environment. See- [Sandboxed Home](../editor_features/home.md#sandboxed-home).--You can also run sandboxed notebooks as scripts:--```console-uv run notebook.py-```--!!! note "Requires uv"-- The default `--sandbox` backend requires the uv package manager- ([installation- instructions](https://docs.astral.sh/uv/getting-started/installation/)).--## Pixi sandboxes--If your notebook needs conda packages, use Pixi as the sandbox backend.-[Install Pixi](https://pixi.prefix.dev/latest/installation/) with support for-`pixi install --script` (available in Pixi 0.80.0). marimo checks this capability-when preparing a notebook's environment; use `pixi self-update` if your-installation predates it.--```bash-marimo edit --sandbox=pixi notebook.py-```--Pixi sandboxes resolve conda dependencies (declared under `[tool.pixi]`-tables in the inline metadata) alongside PyPI dependencies, and require-only pixi — uv is fetched through `pixi exec` when needed. A pixi-notebook also runs standalone with `pixi run --script notebook.py`.--```python-# /// script-# dependencies = ["marimo", "polars"]-#-# [tool.pixi.workspace]-# channels = ["conda-forge"]-#-# [tool.pixi.dependencies]-# gdal = "*"-# ///-```--!!! warning "Pixi limitations"-- - Pixi activation scripts and activation environment variables are not- applied when marimo launches the notebook sandbox.- - `marimo export html-wasm --execute` runs notebooks under- [Pyodide](https://pyodide.org)'s package set, which has no conda- equivalent: notebooks that rely on `[tool.pixi.dependencies]`- cannot be exported to WASM.- - Session and thumbnail exports support `--sandbox=pixi`. Other export- commands still use uv, so conda dependencies are not available there.--!!! tip "Solving the notebook reproducibility crisis"-- marimo's support for package sandboxing is only possible because marimo- notebooks are stored as pure Python files, letting marimo take advantage- of new Python standards like [PEP- 723](https://peps.python.org/pep-0723/) and tools like uv. In contrast,- traditional notebooks like Jupyter are stored as JSON files, and which suffer- from a [reproducibility- crisis](https://leomurta.github.io/papers/pimentel2019a.pdf) due to the lack- of package management.--## Inline script metadata { #auto-tracking-inline-script-metadata }--When running with `--sandbox`, marimo automatically tracks package metadata in-your notebook file using inline script metadata, which per [PEP-723](https://peps.python.org/pep-0723/) is essentially a pyproject.toml inlined-as the script's header. This metadata is used to manage the-notebook's dependencies and Python version, and looks something like this:--```python-# /// script-# requires-python = ">=3.11"-# dependencies = [-# "pandas==<version>",-# "altair==<version>",-# ]-# ///-```--!!! example "Example notebooks"-- The [example- notebooks](https://github.com/marimo-team/marimo/tree/main/examples) in our- GitHub repo were all created using `--sandbox`. Take a look at any of them- for an example of the full script metadata.--### Adding and removing packages--**Using the marimo editor.** When you import a module in the marimo editor, if-marimo detects that it is a third-party package, it will automatically be added-to the script metadata. Removing an import does _not_ remove it from the script-metadata (since library code may still use the package).--Adding packages via the package manager panel will also add packages to script-metadata, and removing packages from the panel will in turn remove them from-the script metadata.--**Adding packages manually.** You can manually manage your notebook's-requirements:--* edit the script metadata manually in an editor like VS Code or neovim.-* use `uv` from the command-line:--```console-uv add --script notebook.py numpy-```--```console-uv remove --script notebook.py numpy-```--### Package locations--By default, marimo will look for packages on PyPI. You can edit the script-metadata to look for packages elsewhere, such as on GitHub. Consult the [Python-packaging-documentation](https://packaging.python.org/en/latest/specifications/dependency-specifiers/#examples)-for more information.--### Local development with editable installs--When developing a local package, you can install it in editable mode using the-`[tool.uv.sources]` section in the script metadata. For example:--```python-# /// script-# requires-python = ">=3.11"-# dependencies = [-# "my-package",-# ]-#-# [tool.uv.sources]-# my-package = { path = "../", editable = true }-# ///-```--This is particularly useful when you want to test changes to your package-without reinstalling it. The package will be installed in "editable" mode,-meaning changes to the source code will be reflected immediately in your-notebook.--### Specifying alternative package indexes--When you need to use packages from a custom PyPI server or alternative index,-you can specify these in your script metadata using the `[[tool.uv.index]]`-section. This is useful for private packages or when you want to use packages-from a specific source.--```python-# /// script-# requires-python = ">=3.11"-# dependencies = [-# "pandas==<version>",-# "private-package==<version>",-# ]-#-# [[tool.uv.index]]-# name = "custom-index"-# url = "https://custom-pypi-server.example.com/simple/"-# explicit = true-#-# [tool.uv.sources]-# private-package = { index = "custom-index" }-# ///-```--In this example:--- `[[tool.uv.index]]` defines a custom package index-- `name` is an identifier for the index-- `url` points to your custom PyPI server-- `explicit = true` means this index will only be used for packages explicitly associated with it-- `[tool.uv.sources]` specifies which packages should come from which indexes--This approach ensures that specific packages are always fetched from your designated custom index, while other packages continue to be fetched from the default PyPI repository.--### Platform-specific dependencies (PEP 508) { #platform-specific-dependencies-pep-508 }--When a notebook runs both locally and as a [WebAssembly notebook](../wasm.md),-you can attach [PEP 508](https://peps.python.org/pep-0508/) environment markers-to individual dependencies. On Pyodide, `sys.platform` is `"emscripten"`.--```python-# /// script-# requires-python = ">=3.11"-# dependencies = [-# "pandas==<version>",-# "torch==<version>; sys_platform != 'emscripten'",-# "pyodide-http; sys_platform == 'emscripten'",-# ]-# ///-```--- `sys_platform != 'emscripten'` — install locally, skip in the browser.-- `sys_platform == 'emscripten'` — install only for WebAssembly / Pyodide.--uv evaluates these markers in sandboxes. marimo also respects them when-pre-installing packages in WASM, when [exporting to WASM-HTML](../exporting/webassembly_html.md), and in the MW003 lint rule for-incompatible packages.--Combine markers with `and` when needed:--```python-# dependencies = [-# "pyzmq>=27.1.0; python_version < '3.15' and sys_platform != 'emscripten'",-# ]-```--For package authors publishing WASM wheels, see [PEP-783](https://peps.python.org/pep-0783/) (`pyemscripten_*_wasm32` tags).--## Configuration--Running marimo in a sandbox environment uses `uv` to create an isolated virtual-environment. You can use any of `uv`'s [supported environment-variables](https://docs.astral.sh/uv/configuration/environment/).--### Choosing the Python version--For example, you can specify the Python version using the `UV_PYTHON` environment variable:--```bash-UV_PYTHON=3.13 marimo edit --sandbox notebook.py-```--### Other common configuration--Another common configuration is `uv`'s link mode:--```bash-UV_LINK_MODE="copy" marimo edit --sandbox notebook.py-```--## Sharing on the web--You can also upload sandboxed notebooks to the web, such as on GitHub, and have-others run them locally with a single command:--```-uvx marimo edit --sandbox https://gist.githubusercontent.com/kolibril13/a59135dd0973b97d488ba21c650667fe/raw/5f98021b5d3c024d5827fa9464787517495178b4/marimo_minimal_numpy_example.py-```--**Note:**--1. This command will run code from a URL. Make sure you trust the source before proceeding.-2. Upon execution, you’ll be prompted:- ```- Would you like to run it in a secure docker container? [Y/n]:- ```- To proceed securely, ensure you have [Docker](https://www.docker.com/) installed and running, then press `Y`.----## Specifying dependencies in Markdown files--Sandboxing support is also provided in [marimo's markdown file-format](../editor_features/watching.md#as-markdown) under the-`pyproject` entry of your frontmatter.--```markdown-----title: My Notebook-marimo-version: 0.0.0-pyproject: |- requires-python: ">=3.11"- dependencies:- - pandas==<version>- - altair==<version>-----```diff --git a/docs/guides/package_management/installing_packages.md b/docs/guides/package_management/installing_packages.mdindex ec28acacd8..458fcca4d1 100644--- a/docs/guides/package_management/installing_packages.md+++ b/docs/guides/package_management/installing_packages.md@@ -1,22 +1,40 @@# Installing packages-marimo supports package management for `pip`, `uv`, `poetry`, `pixi`, and-`rye`. When marimo comes across a module that is not installed, you will be-prompted to install it using your preferred package manager. Once the module is-installed, all cells that depend on the module will be rerun-(or marked as stale).+marimo integrates with your package manager to install packages from the editor.+You can use the sidebar's package panel or accept an installation prompt when+an import is missing.-You can also install (and remove) packages using the package manager sidebar panel.+## Choose a package manager-!!! note "Resolving package names"+For [projects](projects.md), marimo supports pip, uv, Poetry, Pixi, and Rye for+in-editor package management. Select your package manager in marimo's settings.++For [sandboxes](sandboxes.md), marimo supports uv and Pixi. Choose the tool with+a command-line option: `--sandbox` or `--sandbox=uv` for uv, and `--sandbox=pixi`+for Pixi.++## Where packages are installed++Packages installed through the editor go into the environment your notebook+uses. Where their requirements are recorded depends on your workflow.- We use a heuristic for guessing the package name in your registry (e.g. PyPI) from the module name. It is possible that the package name is different from the module name. If you encounter an error, please [file an issue](https://github.com/marimo-team/marimo/issues) or help us by adding your mapping [directly to the codebase](https://github.com/marimo-team/marimo/blob/main/marimo/_runtime/packages/module_name_to_pypi_name.py).+In a **project**, package changes apply to every notebook using the shared+environment. With a project-aware package manager, marimo also updates the+shared requirements and lockfile through the tool's project commands.-**Notes.**+In a **sandbox**, marimo updates the notebook's isolated environment and records+package requirements in its inline metadata, without affecting other notebooks.+The panel also lets you [edit metadata and sync the environment](sandboxes.md#edit-metadata-and-sync-the-environment).++!!! note "PyPI and Conda packages with Pixi"++ The package panel manages Conda dependencies in Pixi projects and PyPI+ dependencies in Pixi sandboxes. For PyPI packages in a project, use+ `pixi add --pypi` from the terminal. For Conda packages in a sandbox, use+ [Pixi-specific metadata or script commands](sandboxes.md#pixi-sandboxes).++!!! note "Resolving package names"-* When using imperative style package managers like `pip`, packages are installed directly-in the active virtual environment.-* When using `uv`, marimo will decide whether to add it to your `pyproject.toml`-(if running as part of a uv project), or whether to install it imperatively with `uv pip` (otherwise).-* When running in a [package sandbox](inlining_dependencies.md), package installation-and removal also updates the notebook's inline dependencies.+ Import names can differ from package names. marimo tries to infer the right+ package; if it guesses incorrectly, [file an issue](https://github.com/marimo-team/marimo/issues)+ or [contribute a mapping](https://github.com/marimo-team/marimo/blob/main/marimo/_runtime/packages/module_name_to_pypi_name.py).diff --git a/docs/guides/package_management/notebooks_in_projects.md b/docs/guides/package_management/notebooks_in_projects.mddeleted file mode 100644index fe38cea557..0000000000--- a/docs/guides/package_management/notebooks_in_projects.md+++ /dev/null@@ -1,183 +0,0 @@-# Notebooks in existing projects--When working with notebooks in existing projects, there are two main approaches-depending on your needs:--1. **Sandbox notebooks** - Self-contained notebooks with isolated dependencies-2. **Project notebooks** - Notebooks that are part of your project's environment--marimo uses [PEP 723](https://peps.python.org/pep-0723/) inline script metadata-for sandboxing, managed by uv. While sandboxing is currently exclusive to the-uv package manager, other package managers may be supported in the future.--For project notebooks, marimo can be added as a project dependency where all-notebooks share the same environment defined in `pyproject.toml`. This approach-works with uv and other package managers (Poetry, Pixi, Hatch, etc.).--## Sandbox notebooks (recommended for libraries)--Sandbox notebooks use inline script metadata ([PEP-723](https://peps.python.org/pep-0723/)) to create isolated environments. This-is ideal when:--- Building examples for a library that users can run independently-- Creating notebooks that don't share dependencies with your main project-- Sharing self-contained notebooks that work anywhere--### Basic sandbox notebook--Sandbox notebooks can be created with:--```bash-marimo edit --sandbox notebook.py-```--When working in the notebook, marimo will automatically manage PEP 723 metadata-for you. This metadata makes the notebook self-contained, meaning you can-either come back later with marimo or run the notebook as a script directly-with uv:--```bash-marimo edit --sandbox notebook.py # automatically loads deps and launches marimo-uv run notebook.py # run notebook as a script-```--### Developing against your local package--When developing library examples, tutorials, or exploratory code, it's often-useful to have notebooks that _use_ your library. In these cases, you can-create and version sandboxed notebooks with your library as an _editable_-install.--This approach lets you:--- Test your library changes immediately without reinstalling-- Add notebook-specific dependencies (like visualization or data processing tools) without polluting your library's requirements-- Create self-contained examples that users can run without your development dependencies--To add your library to a notebook, use uv:--```bash-uv add --script notebooks/notebook.py . --editable-```--This will produce a header that looks like:--```python-# /// script-# requires-python = ">=3.11"-# dependencies = [-# "my-package",-# "pandas",-# "matplotlib",-# ]-#-# [tool.uv.sources]-# my-package = { path = "../", editable = true }-# ///-```--## Project notebooks--For notebooks that are integral to your project, you can manage everything-through your project's `pyproject.toml`. This approach uses a single-environment shared between your project and notebooks.--### Adding marimo to your project--```toml-[project]-name = "my-project"-dependencies = [- "numpy",- "requests",-]--[dependency-groups]-dev = [- "marimo",- "pytest",-]-```--Then work with notebooks using your project's environment:--```bash-# Using uv-uv run marimo edit notebooks/analysis.py--# Or activate the environment-source .venv/bin/activate-marimo edit notebooks/analysis.py-```--This approach:-- Uses a single environment for everything-- Shares dependencies between notebooks and your project-- Follows standard Python project practices--!!! note "Importing from other directories"- If your notebooks need to import modules from directories outside your project, marimo supports configuring the Python path via `pyproject.toml`. However, when possible, it's preferred to avoid path manipulation. We recommend creating a package (`uv init --lib`) and including marimo as a development dependency. For multiple packages, consider configuring [uv workspaces](https://docs.astral.sh/uv/concepts/workspaces/). See the [runtime configuration guide](../configuration/runtime_configuration.md#python-path) for details.--## Examples--### Library with example notebooks--When building a library, use sandbox notebooks for examples that users can run-independently:--```-my-library/-├── pyproject.toml # Library dependencies-├── src/-│ └── my_library/-└── examples/- ├── quickstart.py # Sandbox notebook- └── advanced.py # Sandbox notebook-```--Create example notebooks:-```bash-# Initialize the project-uv init --lib my-library && cd my-library--# Add marimo as development dependency-uv add --dev marimo--# Create a sandbox notebook-mkdir examples-uv run marimo edit --sandbox examples/quickstart.py--# Add your library as editable dependency-uv add --script examples/quickstart.py . --editable-```--### Data science project--When notebooks are part of your analysis workflow, use project notebooks:--```-analysis-project/-├── pyproject.toml # Project + marimo dependencies-├── README.md-├── main.py # Created by uv init-└── notebook.py # Your marimo notebook-```--Set up the project:-```bash-# Initialize project-uv init analysis-project && cd analysis-project--# Add marimo as a project dependency-uv add marimo pandas scikit-learn--# Edit notebooks using project environment-uv run marimo edit notebook.py-```--## Related guides--- [Using uv](using_uv.md) - Detailed guide on uv with marimo-- [Inlining dependencies](inlining_dependencies.md) - More on self-contained notebooks-- [Package management overview](index.md) - General package management in marimodiff --git a/docs/guides/package_management/projects.md b/docs/guides/package_management/projects.mdnew file mode 100644index 0000000000..57d4c6619d--- /dev/null+++ b/docs/guides/package_management/projects.md@@ -0,0 +1,202 @@+# Working in projects++Notebooks in a project _share_ package requirements with other notebooks and+scripts. Those requirements live in a shared configuration file, such as+`pyproject.toml`, and all the notebooks in a project run in an environment with+those packages.++The [package management overview](index.md) compares shared projects with notebooks+that carry their own requirements.++## Set up your project { #open-a-notebook }++### With a project manager { #add-marimo-to-your-project }++Adding marimo to your project's requirements lets you open notebooks with the+same packages as the rest of your code. Choose your project manager below for+setup instructions.++=== "uv"++ If you're starting a new project, run `uv init` in your project directory+ or start from the [marimo uv starter template](https://github.com/marimo-team/marimo-uv-starter-template).+ To add marimo to the project's requirements, run:++ ```bash+ uv add marimo+ ```++ You can then open a notebook with the project's installed marimo and packages:++ ```bash+ uv run marimo edit notebook.py+ ```++ For a library where marimo is a development tool, use `uv add --dev marimo`.+ See [uv's project guide](https://docs.astral.sh/uv/guides/projects/) for more+ about managing project dependencies.++=== "Pixi"++ If you're starting a new project, run `pixi init --format pyproject` in your+ project directory to create a `pyproject.toml`. To add marimo to the+ project's requirements, run:++ ```bash+ pixi add --pypi marimo+ ```++ The `--pypi` flag installs marimo from PyPI. Pixi can also install Conda+ packages; see its guide to [managing Conda and PyPI dependencies](https://pixi.prefix.dev/latest/python/tutorial/#managing-both-conda-and-pypi-dependencies).++ You can then open a notebook with the project's installed marimo and packages:++ ```bash+ pixi run marimo edit notebook.py+ ```++=== "Poetry"++ If you're starting a new project, run `poetry init` in your project directory+ to create a `pyproject.toml`. To add marimo to the project's requirements, run:++ ```bash+ poetry add marimo+ ```++ You can then open a notebook with the project's installed marimo and packages:++ ```bash+ poetry run marimo edit notebook.py+ ```++ See [Poetry's project guide](https://python-poetry.org/docs/basic-usage/)+ for more about managing project dependencies.++Replacing `notebook.py` with `notebooks/` opens a directory of notebooks.+They use the same project environment unless you enable sandbox mode.++### With an environment you manage { #use-an-existing-environment }++With pip, or an environment you already manage, marimo is installed alongside+your notebook's packages. Activating the environment makes its `python` and+`marimo` commands available in your shell.++If you don't already have an environment, create one:++```bash+python -m venv .venv+```++Activate it in each new terminal session:++=== "macOS / Linux"++ ```bash+ source .venv/bin/activate+ ```++=== "Windows (PowerShell)"++ ```powershell+ .venv\Scripts\Activate.ps1+ ```++Then install marimo and your packages, and open a notebook:++```bash+python -m pip install marimo numpy+marimo edit notebook.py+```++To return to the notebook later, activate the same environment and run+`marimo edit notebook.py`.++If you use Conda, activate your Conda environment and+[install marimo there](../../getting_started/installation.md) instead.++Installing packages with pip does not automatically update the project's+requirements files, so the requirements need to be maintained separately for+others to install the same packages.++## Manage shared dependencies++The editor's [package panel](installing_packages.md) lets you add and remove+packages as you work. You can also use your project manager from the terminal:++=== "uv"++ ```bash+ uv add numpy+ uv remove numpy+ ```++=== "Pixi"++ ```bash+ pixi add numpy+ pixi remove numpy+ ```++=== "Poetry"++ ```bash+ poetry add numpy+ poetry remove numpy+ ```++Package changes apply to all notebooks using the shared environment. Sharing+the project's requirements file and any lockfile with your notebooks lets+collaborators install the recorded dependencies.++In a manually managed environment, packages can be installed with pip or your+environment's package manager.++## Import your project's code++Notebooks can import your project's Python package when it is installed in the+shared environment. An **editable installation** uses the source files directly,+so you can develop the package without reinstalling it after each change.++For example, a uv library project created with `uv init --lib my-library` can+have this layout:++```text+my-library/+├── pyproject.toml+├── uv.lock+├── src/+│ └── my_library/+│ └── __init__.py+└── notebooks/+ └── analysis.py+```++With marimo added to this project, `uv run marimo edit notebooks/analysis.py`+installs the library in editable mode and opens the notebook. Its cells can then+`import my_library`.++See [importing local modules](importing_local_code.md#importing-local-modules)+for other layouts and [module autoreloading](../editor_features/module_autoreloading.md)+for how marimo picks up source changes.++## Run notebooks as scripts++The same project requirements can be used to+[run notebooks as scripts](../scripts.md#running-in-a-project) without opening+the editor. That guide covers command-line arguments and scheduled execution.++## Keep standalone examples in a project++A repository can contain both project notebooks and notebooks with their own+requirements. For example, a tutorial might need extra packages that other+notebooks in the project don't use.++[Sandbox mode](sandboxes.md) prepares a separate environment for each notebook+without inheriting the project's packages. A notebook that uses your local+library needs to declare it, for example as an+[editable dependency](sandboxes.md#local-development-with-editable-installs).++A local path dependency still needs its source files when shared. A published+package or another accessible source lets others run the notebook without+cloning the surrounding repository.diff --git a/docs/guides/package_management/sandboxes.md b/docs/guides/package_management/sandboxes.mdnew file mode 100644index 0000000000..142c69b05b--- /dev/null+++ b/docs/guides/package_management/sandboxes.md@@ -0,0 +1,347 @@+# Working in sandboxes++A notebook can carry its code and package requirements in the same file.+In sandbox mode, marimo prepares an **isolated environment** from the notebook's+requirements, independently of other notebooks or a surrounding project.++See the [package management overview](index.md) for when to use a sandbox or+[shared project requirements](projects.md).++## Open a notebook++marimo can prepare a notebook's sandbox with uv or Pixi. Choose your tool below+to open a notebook using its own requirements, without setting up a project.++=== "uv"++ With [uv installed](https://docs.astral.sh/uv/getting-started/installation/),+ you can use `uvx` to launch marimo and open your notebook:++ ```bash+ uvx marimo edit --sandbox notebook.py+ ```++ `uvx` installs and launches marimo, while `--sandbox` tells marimo to use+ uv to prepare a separate environment for the notebook's packages. uv is+ the default sandbox backend and installs Python packages from PyPI.++ If marimo is already installed, you can run+ `marimo edit --sandbox notebook.py` directly.++=== "Pixi"++ With [Pixi installed](https://pixi.prefix.dev/latest/installation/),+ you can use `pixi exec` to launch marimo and open your notebook:++ ```bash+ pixi exec marimo edit --sandbox=pixi notebook.py+ ```++ `pixi exec` installs and launches marimo, while+ `--sandbox=pixi` prepares the notebook's separate environment using Pixi,+ with support for both PyPI and Conda packages.++ If marimo is already installed, you can run+ `marimo edit --sandbox=pixi notebook.py` directly. Sandbox support requires+ Pixi 0.80.0 or later.++marimo starts the server that provides the editor separately from the notebook's+isolated environment. The editor can open while the notebook's packages are+being installed; the notebook's code runs once installation completes.++If installation fails, the editor remains available. You can inspect the error,+[edit the notebook's requirements and retry](#edit-metadata-and-sync-the-environment)+from the package panel, without restarting the marimo server.++The same sandbox option works with `marimo new` to create a notebook and+`marimo run` to serve it as an app.++The `--no-sandbox` option uses your current environment instead of the notebook's+requirements.++!!! note "Dependency isolation"++ Sandboxes isolate installed packages, not access to your files or network.+ Only run notebooks from sources you trust.++## Open a directory of notebooks++To work with several sandboxed notebooks, pass a directory instead of a file:++=== "uv"++ ```bash+ marimo edit --sandbox notebooks/+ ```++=== "Pixi"++ ```bash+ marimo edit --sandbox=pixi notebooks/+ ```++marimo opens the [home page](../editor_features/home.md#sandboxed-home) for the+directory. Each notebook gets its own environment, prepared from its requirements+when you open it. Package changes in one notebook do not affect the others.++## Manage notebook dependencies++### Inline script metadata { #auto-tracking-inline-script-metadata }++Python version and package requirements are recorded in a comment block at the+top of the notebook, using [inline script metadata (PEP 723)](https://peps.python.org/pep-0723/).++```python title="notebook.py (header)"+# /// script+# requires-python = ">=3.11"+# dependencies = [+# "marimo",+# "pandas",+# "altair",+# ]+# ///+```++The `requires-python` field specifies the Python version requirement, and+`dependencies` lists Python packages, typically from PyPI. marimo uses the+metadata to prepare the notebook's environment; uv and Pixi can also read it to+[run the notebook as a script](#run-and-share-the-notebook).++### Add and remove packages { #adding-and-removing-packages }++When you add or remove Python packages through the+[package panel](installing_packages.md), marimo updates both the notebook's+metadata and its environment, including when you accept a prompt to install+a missing package.++Removing an import alone does not remove its package requirement, since other+code may still need it.++You can also manage requirements from the terminal:++=== "uv"++ Use `uv add` or `uv remove` with `--script` to update the notebook's+ requirements rather than a project's:++ ```bash+ uv add --script notebook.py numpy+ uv remove --script notebook.py numpy+ ```++=== "Pixi"++ Use `pixi add` or `pixi remove` with `--script` to update the notebook's+ requirements. The `--pypi` flag selects Python packages from PyPI:++ ```bash+ pixi add --script notebook.py --pypi numpy+ pixi remove --script notebook.py --pypi numpy+ ```++<a id="edit-metadata-and-sync-the-environment"></a>++!!! tip "Edit metadata directly"++ For tool-specific settings or dependency problems, use **Edit manifest…** in+ the package panel to edit the notebook's metadata and sync its environment,+ even if sandbox setup has failed.++<a id="local-development-with-editable-installs"></a>++### Tool-specific configuration { #backend-specific-metadata }++Inline metadata can include settings specific to uv or Pixi. For example, a+sandbox needs an explicit dependency on a local library, since it doesn't+inherit project packages. An editable install lets the notebook use the+library's source without reinstalling after each change.++=== "uv"++ With `--sandbox=uv`, declare the local package in `tool.uv.sources`:++ ```python title="notebook.py (header)"+ # /// script+ # dependencies = ["marimo", "my-library"]+ #+ # [tool.uv.sources]+ # my-library = { path = "./my-library", editable = true }+ # ///+ ```++ See [uv's script guide](https://docs.astral.sh/uv/guides/scripts/) for more+ settings, including custom package indexes.++=== "Pixi"++ With `--sandbox=pixi`, declare the local package in `tool.pixi.pypi-dependencies`:++ ```python title="notebook.py (header)"+ # /// script+ # dependencies = ["marimo"]+ #+ # [tool.pixi.workspace]+ # channels = ["conda-forge"]+ #+ # [tool.pixi.pypi-dependencies]+ # my-library = { path = "./my-library", editable = true }+ # ///+ ```++ marimo does not apply Pixi activation scripts or activation environment variables.++The `./my-library` path is relative to the notebook. See+[module autoreloading](../editor_features/module_autoreloading.md) for how+marimo picks up source changes in an open notebook.++### Conda packages with Pixi { #pixi-sandboxes }++Pixi can manage non-Python dependencies, including system libraries and language+runtimes, alongside Python packages. For example, a notebook can include the R+runtime and [rpy2](https://rpy2.github.io/) from Conda to call R+from Python:++```python title="notebook.py (header)"+# /// script+# dependencies = ["marimo"]+#+# [tool.pixi.workspace]+# channels = ["conda-forge"]+#+# [tool.pixi.dependencies]+# r-base = "*"+# rpy2 = "*"+# ///+```++When you open the notebook with `marimo edit --sandbox=pixi notebook.py`,+Pixi installs marimo from PyPI and R and rpy2 from Conda. A Python cell+can then summarize R's built-in `iris` dataset:++```python+import rpy2.robjects as ro++print(ro.r("summary(iris)"))+```++For an interactive example combining a marimo slider, dplyr, Arrow, and Polars,+see the [Using R notebook](https://github.com/marimo-team/marimo/blob/main/examples/misc/using_r.py).++Manage [Conda dependencies](https://pixi.prefix.dev/latest/python/scripts/#manage-dependencies)+through the metadata or Pixi's script commands; marimo's package panel manages+PyPI dependencies.++### Using packages across platforms { #platform-specific-dependencies-pep-508 }++Some packages are needed only on certain platforms—for example, when running a+notebook locally versus in the browser with [WebAssembly](../wasm.md).+[Environment markers](https://peps.python.org/pep-0508/#environment-markers)+let you specify where each dependency should be installed.++For browser execution, Pyodide uses `"emscripten"` as its `sys.platform` value:++```python+# /// script+# requires-python = ">=3.11"+# dependencies = [+# "pandas",+# "torch; sys_platform != 'emscripten'",+# "pyodide-http; sys_platform == 'emscripten'",+# ]+# ///+```++- `sys_platform != 'emscripten'` — install locally, skip in the browser.+- `sys_platform == 'emscripten'` — install only for WebAssembly / Pyodide.++Environment markers also apply when [exporting to WebAssembly+HTML](../exporting/webassembly_html.md). WebAssembly uses Pyodide's package set+and cannot install Conda dependencies.++## Run and share the notebook++The notebook file contains the requirements needed to prepare its environment.+If it doesn't depend on other local files, you can share it on its own, along+with the sandbox command you used to open it.++Any required data or local source files still need to be shared. Recipients with+uv or Pixi installed can open the notebook in marimo, or+[run it as a script](../scripts.md#running-with-inline-dependencies) using the+same inline requirements.++### Lock dependency versions++marimo updates the notebook's inline requirements as you manage packages in the+editor. Creating a **lockfile** is a separate step: use your package manager to+record exact versions, including dependencies of dependencies.++=== "uv"++ ```bash+ uv lock --script notebook.py+ ```++ uv writes `notebook.py.lock` alongside the notebook. See+ [uv's locking guide](https://docs.astral.sh/uv/guides/scripts/#locking-dependencies)+ for how subsequent commands use and update the lockfile.++=== "Pixi"++ ```bash+ pixi lock --script notebook.py+ ```++ Pixi writes `notebook.py.pixi.lock` alongside the notebook. See+ [Pixi's locking guide](https://pixi.prefix.dev/latest/python/scripts/#lock-exact-versions)+ for platform requirements and how subsequent commands use the lockfile.++Share the lockfile with the notebook so others can reuse the resolved versions.++### Sharing on the web { #sharing-on-the-web }++For a notebook hosted online, replace the file path in your sandbox command+with its URL. For example, you can open a notebook shared as a GitHub Gist:++=== "uv"++ ```bash+ uvx marimo edit --sandbox https://gist.github.com/kolibril13/a59135dd0973b97d488ba21c650667fe+ ```++=== "Pixi"++ ```bash+ pixi exec marimo edit --sandbox=pixi https://gist.github.com/kolibril13/a59135dd0973b97d488ba21c650667fe+ ```++Only run remote code you trust; a sandbox isolates packages, not access to your+files or network.++## Markdown notebooks { #specifying-dependencies-in-markdown-files }++marimo's sandbox mode also supports [Markdown notebooks](../editor_features/watching.md#as-markdown)+with either uv or Pixi:++=== "uv"++ ```bash+ uvx marimo edit --sandbox notebook.md+ ```++=== "Pixi"++ ```bash+ pixi exec marimo edit --sandbox=pixi notebook.md+ ```++Package requirements are stored as TOML under `pyproject` in the notebook's+frontmatter:++```markdown title="notebook.md (frontmatter)"+---+title: My Notebook+pyproject: |+ requires-python = ">=3.11"+ dependencies = ["marimo", "pandas", "altair"]+---+```diff --git a/docs/guides/package_management/using_uv.md b/docs/guides/package_management/using_uv.mddeleted file mode 100644index 592fd315e6..0000000000--- a/docs/guides/package_management/using_uv.md+++ /dev/null@@ -1,173 +0,0 @@-# Using uv--[uv](https://docs.astral.sh/uv/) is an extremely fast Python package and-project manager: you can use it to install packages, manage the dependencies-of Python projects, and run scripts. While marimo supports all major package-managers, it integrates especially tightly with uv. In particular, marimo's-package sandbox feature, which lets you [inline-dependencies](inlining_dependencies.md) in notebook files, requires uv.--!!! note "No prior knowledge required"-- This guide teaches you the basics of using `uv` with marimo. It assumes zero- familiarity with `uv`.--You can manage your notebooks' dependencies in three different ways:--1. inline dependencies: [inlining dependencies](inlining_dependencies.md) in notebook files, using `marimo edit --sandbox notebook.py`-2. projects: using a `uv` project , which define dependencies declaratively in a `pyproject.toml`- file;-3. non-project environment: dependencies are imperatively installed--We'll walk through each of these three ways in this guide.--## Using inline dependencies--The easiest way to get started is to use marimo's [package sandbox-feature](inlining_dependencies.md), which manages your dependencies for you.-Create or edit your notebook with [`uvx`-command](https://docs.astral.sh/uv/concepts/tools/#the-uv-tool-interface),-making sure to include the `--sandbox` flag:--<!-- TODO propagating marimo version into the script metadata -->--```console-uvx marimo edit --sandbox my_notebook.py-```--This command installs marimo in a temporary environment, activates it, then-runs your marimo notebook. The `--sandbox` flag is what tells marimo to keep-track of your dependencies and store them in the notebook file. If there are-any dependencies already tracked in the file, this command will download-them and install them in the environment.--Run sandboxed notebooks as scripts with--```console-uv run my_notebook.py-```--### From URLs--You can also upload sandboxed notebooks to the web, such as on GitHub, and have others run-them locally with a single command:--```-uvx marimo edit --sandbox https://gist.githubusercontent.com/kolibril13/a59135dd0973b97d488ba21c650667fe/raw/5f98021b5d3c024d5827fa9464787517495178b4/marimo_minimal_numpy_example.py-```--**Note:**--1. This command will run code from a URL. Make sure you trust the source before proceeding.-2. Upon execution, you’ll be prompted:- ```- Would you like to run it in a secure docker container? [Y/n]:- ```- To proceed securely, ensure you have [Docker](https://www.docker.com/) installed and running, then press `Y`.---To learn more, read our full guide on using [inline dependencies](inlining_dependencies.md).--## Using uv projects--A [`uv` project](https://docs.astral.sh/uv/guides/projects/) is a directory in which you can store Python code, including-notebooks, alongside a pyproject.toml file that declares the project's-dependencies.--### Creating a project--Create a project with `uv init`:--```console-uv init hello-world-cd hello-world-```--!!! tip "Starter template"-- Get started quickly by cloning our [starter template](https://github.com/marimo-team/marimo-uv-starter-template).---This creates a pyproject.toml and some starter code.--Next, add marimo to your project:--```console-uv add marimo-```--??? note "Omitting marimo from your project"-- Adding marimo to your project is optional. Instead, you can- run marimo in a temporary environment that has access to- your project's dependencies using `uv run --with marimo marimo edit`.--### Running marimo--Once you've added marimo, use the `uv run` command-to run the version of marimo installed in your project:--```console-uv run marimo edit my_notebook.py-```--Starting marimo in this way will let marimo import any of the packages-installed in your project.--**Scripts.** Run marimo notebooks as scripts with--```console-uv run my_notebook.py-```--which will run your notebook in an environment containing your project dependencies.--### Adding and removing dependencies--#### Using the uv command-line--Use `uv add` to add dependencies:--```console-uv add numpy-```--You can also specify a version--```console-uv add numpy==2.26-```--Remove packages with `uv remove`:--```console-uv remove numpy-```--#### Using the marimo editor--If you started marimo with `uv run marimo edit`, the marimo editor's [package-management features](installing_packages.md) will add and remove packages from-your pyproject.toml, so there's no need to use the `uv` command-line if you-don't want to.--## Using marimo in a non-project environment--If you are used to a venv and pip based workflow, you can use the `uv venv` and-`uv pip` commands for a similar but more performant experience:--* `uv venv` creates a virtual environment in the current directory, at `.venv`-* `uv pip` lets you install and uninstall packages in the venv--### Example---```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.diff --git a/docs/guides/publishing/self_host_wasm.md b/docs/guides/publishing/self_host_wasm.mdindex 1a03171292..689862e6db 100644--- a/docs/guides/publishing/self_host_wasm.md+++ b/docs/guides/publishing/self_host_wasm.md@@ -40,7 +40,7 @@ The HTML uses relative URLs for the bundled runtime, lockfile, and packageindex, so the directory can be moved to another host or URL prefix. The`packages` directory includes transitive dependencies, packages inferred fromimports that are available in Pyodide, and dependencies declared in-[inline script metadata](../package_management/inlining_dependencies.md).+[inline script metadata](../package_management/sandboxes.md).Declare PyPI dependencies in that metadata, including packages installeddynamically by the notebook.diff --git a/docs/guides/publishing/thumbnails.md b/docs/guides/publishing/thumbnails.mdindex 8fa032be31..a26dfd1089 100644--- a/docs/guides/publishing/thumbnails.md+++ b/docs/guides/publishing/thumbnails.md@@ -72,7 +72,7 @@ By default, thumbnails are generated without executing the notebook (fast; no ouinstalled. Use `--no-sandbox` to disable sandboxing and dependency prompts.Sandboxed execution installs dependencies from inline script metadata- (PEP 723). See [Inlining dependencies](../package_management/inlining_dependencies.md).+ (PEP 723). See [Inlining dependencies](../package_management/sandboxes.md).Each notebook executes in its own process using its inline dependencies.Playwright is installed for the renderer without adding it to notebookdiff --git a/docs/guides/scripts.md b/docs/guides/scripts.mdindex e8f4f9e39c..a27ee52732 100644--- a/docs/guides/scripts.md+++ b/docs/guides/scripts.md@@ -1,4 +1,4 @@-# Run as a script+# Run notebooks as scriptsYou can run marimo notebooks as scripts at the command line, just likeany other Python script. For example,@@ -7,20 +7,77 @@ any other Python script. For example,python my_marimo_notebook.py```+The `python` command uses your current environment, which must contain marimo and the+notebook's dependencies. Activate it first if you manage it yourself.++uv and Pixi can prepare the environment and run the script using its+[declared dependencies](#running-with-declared-dependencies).+Running a notebook as a script is useful when your notebook has side-effects,like writing to disk. Print statements and other console outputs will showup in your terminal.-marimo notebooks can also [double as importable-modules](https://docs.marimo.io/guides/reusing_functions/), providing libraries-of functions and classes that you can reuse in other programs:+You can also [import functions and classes](reusing_functions.md) from notebooks+into other Python programs.-```python-from my_notebook import my_function-```-Read our guide on [reusable functions](reusing_functions.md) for details.+## Running with declared dependencies++Use your package manager to run a notebook with its declared requirements.++### Running with inline dependencies++A [sandboxed notebook](package_management/sandboxes.md) declares+its requirements as inline script metadata (PEP 723). uv and Pixi can read that+metadata, prepare an environment, and run the notebook without opening the editor:++=== "uv"++ ```bash+ uv run notebook.py+ ```++=== "Pixi"++ ```bash+ pixi run --script notebook.py+ ```++Use Pixi for notebooks that require Conda dependencies declared under+`tool.pixi`. Running a notebook with `python` directly does not install its+inline requirements.++### Running in a project++For a notebook that uses [project dependencies](package_management/projects.md),+run it from the project directory:++=== "uv"++ ```bash+ uv run notebook.py+ ```++ If the notebook contains inline script metadata, uv uses that metadata+ instead of the project's dependencies.++=== "Pixi"++ ```bash+ pixi run python notebook.py+ ```++ `pixi run python` uses the workspace environment. Use `pixi run --script notebook.py`+ instead to prepare an environment from the notebook's inline requirements.++=== "Poetry"++ ```bash+ poetry run python notebook.py+ ```+See [package management](package_management/index.md) for choosing between+project dependencies and a notebook sandbox.!!! tip "Check before running"@@ -90,7 +147,7 @@ functions](reusing_functions.md) from notebooks in other jobs as well.### GitHub Action-Run notebooks on a schedule with [GitHub Actions](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule). This example assumes [inline dependencies](package_management/inlining_dependencies.md):+Run notebooks on a schedule with [GitHub Actions](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule). This example assumes [inline dependencies](package_management/sandboxes.md):```yamlname: Run marimo notebook dailydiff --git a/docs/guides/wasm.md b/docs/guides/wasm.mdindex f99bdfdcbb..d9c4526e73 100644--- a/docs/guides/wasm.md+++ b/docs/guides/wasm.md@@ -73,7 +73,7 @@ unlike molab, notebooks created at the playground are not saved.notebooks, create them with `marimo edit --sandbox notebook.py`. Thisinlines your package dependencies into the notebook file, ensuring theyare seamlessly installed in our WebAssembly environment. See- [package management](editor_features/package_management.md) for more details.+ [package management](package_management/sandboxes.md) for more details.!!! tip "Rendering performance"@@ -146,7 +146,7 @@ deps marked `sys_platform != 'emscripten'` are not flagged for WASM).uv and pip evaluate markers when installing with `--sandbox`, so the samemetadata works for local sandboxes and WASM exports. See also-[Inlining dependencies](package_management/inlining_dependencies.md#platform-specific-dependencies-pep-508).+[Inlining dependencies](package_management/sandboxes.md#platform-specific-dependencies-pep-508).## Including datadiff --git a/docs/index.md b/docs/index.mdindex 88dd23a5f3..004c77901d 100644--- a/docs/index.md+++ b/docs/index.md@@ -83,7 +83,7 @@ reproducibility, maintainability, composability, and shareability.- 🐍 **git-friendly:** stored as `.py` files- 🛢️ **designed for data**: query dataframes, databases, warehouses, and lakehouses [with SQL](guides/working_with_data/sql.md); filter and search [dataframes](guides/working_with_data/dataframes.md)- 🤖 **AI-native**: [pair with AI agents](https://marimo.io/pair) like Claude Code, or use our editor's [built-in AI features](guides/editor_features/ai_completion/)-- 🔬 **reproducible:** [no hidden state](guides/reactivity.md), deterministic execution, [built-in package management](guides/editor_features/package_management.md)+- 🔬 **reproducible:** [no hidden state](guides/reactivity.md), deterministic execution, [built-in package management](guides/package_management/installing_packages.md)- 🏃 **executable:** [execute as a Python script](guides/scripts.md), parameterized by CLI args- 🛜 **shareable**: [deploy as an interactive web app](guides/apps.md) or [slides](guides/apps.md#slides-layout), [run in the browser via WASM](guides/wasm.md)- 🧩 **reusable:** [import functions and classes](guides/reusing_functions.md) from one notebook to another@@ -163,11 +163,11 @@ Your notebooks are still pure Python, even if they use SQL.dynamic stories that depend on Python data.**Built-in package management.** marimo has built-in support for all major-package managers, letting you [install packages on import](guides/editor_features/package_management.md). marimo can even+package managers, letting you [install packages on import](guides/package_management/installing_packages.md). marimo can even[serialize package-requirements](guides/package_management/inlining_dependencies.md)+requirements](guides/package_management/sandboxes.md)in notebook files, and auto install them in-isolated venv sandboxes.+isolated environments.**Deterministic execution order.** Notebooks are executed in a deterministicorder, based on variable references instead of cells' positions on the page.diff --git a/docs/vercel.json b/docs/vercel.jsonindex 8342af3fe7..0f399e8353 100644--- a/docs/vercel.json+++ b/docs/vercel.json@@ -17,7 +17,27 @@"redirects": [{"source": "/guides/package_reproducibility/",- "destination": "/guides/package_management/inlining_dependencies/",+ "destination": "/guides/package_management/sandboxes/",+ "permanent": true+ },+ {+ "source": "/guides/package_management/inlining_dependencies.html",+ "destination": "/guides/package_management/sandboxes/",+ "permanent": true+ },+ {+ "source": "/guides/package_management/notebooks_in_projects.html",+ "destination": "/guides/package_management/projects/",+ "permanent": true+ },+ {+ "source": "/guides/package_management/importing_packages.html",+ "destination": "/guides/package_management/importing_local_code/",+ "permanent": true+ },+ {+ "source": "/guides/package_management/using_uv.html",+ "destination": "/guides/package_management/","permanent": true},{@@ -522,7 +542,7 @@},{"source": "/guides/editor_features/package_management.html",- "destination": "/guides/editor_features/package_management/",+ "destination": "/guides/package_management/installing_packages/","permanent": true},{diff --git a/examples/misc/README.md b/examples/misc/README.mdindex adf5868f57..6086d9504f 100644--- a/examples/misc/README.md+++ b/examples/misc/README.md@@ -20,3 +20,11 @@ comment. Here are the steps to open an example notebook:You can also open notebooks without `uv`, with just `marimo edit <notebook.py>`;however, you'll need to install the requirements yourself.++The [Using R](using_r.py) example uses Pixi to install R and its packages+alongside Python dependencies. With [Pixi installed](https://pixi.prefix.dev/latest/installation/),+open it with:++```bash+marimo edit --sandbox=pixi examples/misc/using_r.py+```diff --git a/examples/misc/using_r.py b/examples/misc/using_r.pynew file mode 100644index 0000000000..bfb8d634ec--- /dev/null+++ b/examples/misc/using_r.py@@ -0,0 +1,87 @@+# /// script+# requires-python = ">=3.12,<3.13"+# dependencies = [+# "marimo",+# "polars>=1",+# "pyarrow>=17",+# "rpy2>=3.6",+# "rpy2-arrow==0.1.3",+# ]+#+# [tool.pixi.workspace]+# channels = ["conda-forge"]+#+# [tool.pixi.dependencies]+# r-base = "*"+# r-dplyr = "*"+# r-arrow = ">=17"+# ///++import marimo++__generated_with = "0.24.2"+app = marimo.App()++with app.setup:+ import os++ # Load R from the Pixi environment at runtime.+ os.environ["RPY2_CFFI_MODE"] = "ABI"++ import marimo as mo+ import polars as pl+ import rpy2.robjects+ import rpy2_arrow.arrow++[email protected](hide_code=True)+def _():+ mo.md("""+ # Using R++ With Pixi sandboxing, a marimo notebook can describe more than its Python+ dependencies, including system libraries and even another language's runtime.++ This demo declares R and Python dependencies together, uses marimo's+ reactivity to run R code when a slider changes, and shares the resulting+ Arrow table back to Python without copying its data.++ With [Pixi installed](https://pixi.prefix.dev/latest/installation/), open+ this notebook in a Pixi sandbox to install both its R and Python dependencies:++ ```bash+ marimo edit --sandbox=pixi examples/misc/using_r.py+ ```+ """)+ return+++def _():+ min_len = mo.ui.slider(+ start=4.0,+ stop=8.0,+ step=0.1,+ value=5.0,+ label="Minimum sepal length (cm)",+ )+ min_len+ return (min_len,)+++def _(min_len):+ r_table = rpy2.robjects.r(f"""+ iris |>+ dplyr::filter(Sepal.Length >= {min_len.value}) |>+ dplyr::mutate(Species = as.character(Species)) |>+ arrow::arrow_table()+ """)++ df = pl.from_arrow(rpy2_arrow.arrow.rarrow_to_py_table(r_table))+ df+ return (df,)+++if __name__ == "__main__":+ app.run()diff --git a/mkdocs.yml b/mkdocs.ymlindex 8a25d12a73..da0e2a449a 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -104,11 +104,10 @@ nav:- Setup References: guides/understanding_errors/setup.md- Package management:- Package management: guides/package_management/index.md- - Importing packages: guides/package_management/importing_packages.md+ - Working in projects: guides/package_management/projects.md+ - Working in sandboxes: guides/package_management/sandboxes.md- Installing packages: guides/package_management/installing_packages.md- - Inlining dependencies: guides/package_management/inlining_dependencies.md- - Notebooks in existing projects: guides/package_management/notebooks_in_projects.md- - Using uv: guides/package_management/using_uv.md+ - Importing local code: guides/package_management/importing_local_code.md- Generate with AI:- Generate with AI: guides/generate_with_ai/index.md- Pair with agents via marimo pair: guides/generate_with_ai/marimo_pair.md@@ -127,7 +126,6 @@ nav:- AI tools: guides/editor_features/tools.md- Agents: guides/editor_features/agents.md- Language Server: guides/editor_features/language_server.md- - Package management: guides/editor_features/package_management.md- Using your own editor: guides/editor_features/watching.md- Run notebooks as apps: guides/apps.md- Run notebooks as scripts: guides/scripts.md@@ -321,7 +319,12 @@ plugins:font_family: Roboto- tags- redirects:- redirect_maps: {}+ redirect_maps:+ guides/package_management/using_uv.md: guides/package_management/index.md+ guides/package_management/notebooks_in_projects.md: guides/package_management/projects.md+ guides/package_management/inlining_dependencies.md: guides/package_management/sandboxes.md+ guides/package_management/importing_packages.md: guides/package_management/importing_local_code.md+ guides/editor_features/package_management.md: guides/package_management/installing_packages.md- mkdocstrings:handlers:python: