Skip to main content
marimo provides built-in package management using PEP 723 inline script metadata. Dependencies are declared directly in your notebook and can be automatically installed in isolated environments.

​
PEP 723 Script Metadata

marimo notebooks can include dependency information at the top of the file:
notebook.py
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "marimo",
#     "pandas>=2.0.0",
#     "plotly>=5.0.0",
#     "scikit-learn",
# ]
# ///

import marimo

app = marimo.App()

@app.cell
def __():
    import pandas as pd
    import plotly.express as px
    from sklearn.linear_model import LinearRegression
    return pd, px, LinearRegression
The # /// markers define a PEP 723 metadata block. This is a standard format supported by tools like uv.

​
Auto-Install with uv

When using --sandbox mode, marimo automatically manages dependencies using uv.

​
Installing uv

First, install uv: 
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# With pip
pip install uv

​
Running in Sandbox Mode

# marimo automatically detects dependencies and prompts
marimo edit notebook.py

# Or explicitly use sandbox mode
marimo edit notebook.py --sandbox
When you open a notebook with dependencies:
  1. marimo detects the PEP 723 metadata
  2. Prompts: “Run in a sandboxed venv?”
  3. Creates an isolated environment with uv
  4. Installs all dependencies automatically
  5. Runs the notebook in that environment
Use marimo -y edit notebook.py to auto-accept the sandbox prompt.
# Each notebook gets its own sandboxed environment
marimo edit ./notebooks --sandbox
For directories:
  • Each notebook has its own isolated venv
  • Dependencies are per-notebook, not shared
  • Requires pyzmq for IPC communication:
pip install marimo[sandbox]

​
Managing Dependencies

​
Adding Packages

marimo provides a UI for adding packages, or you can use uv directly: 
# Add a package to the script metadata
uv add --script notebook.py requests

# Add a versioned package
uv add --script notebook.py "pandas>=2.0.0"

# Add multiple packages
uv add --script notebook.py numpy scipy matplotlib
This updates the metadata block: 
# /// script
# dependencies = [
#     "marimo",
#     "requests",
#     "pandas>=2.0.0",
#     "numpy",
#     "scipy",
#     "matplotlib",
# ]
# ///

​
Version Constraints

Specify version requirements using standard pip syntax: 
# /// script
# dependencies = [
#     "pandas>=2.0.0",        # Minimum version
#     "numpy==1.24.0",        # Exact version
#     "scipy>=1.10,<2.0",     # Range
#     "matplotlib~=3.7.0",    # Compatible release
# ]
# ///

​
Python Version

Specify required Python version: 
# /// script
# requires-python = ">=3.11"
# dependencies = [...]
# ///
marimo will use this version when creating the sandbox environment.

​
Package Sources

​
Custom Index URLs

Use private PyPI servers or mirrors: 
# /// script
# dependencies = ["my-private-package"]
#
# [tool.uv]
# index-url = "https://pypi.company.com/simple"
# ///

​
Extra Index URLs

Combine multiple package sources: 
# /// script
# dependencies = ["public-pkg", "private-pkg"]
#
# [tool.uv]
# extra-index-url = ["https://private.pypi.org/simple"]
# ///

​
Named Indexes

Use named indexes for better control: 
# /// script
# dependencies = ["my-package"]
#
# [[tool.uv.index]]
# url = "https://custom-index.com/simple"
# ///

​
Auto-Install on Import

When running without --sandbox, marimo can detect missing packages: 
@app.cell
def __():
    # marimo detects if requests is not installed
    import requests
    return (requests,)
Auto-install without sandbox installs packages globally. Use --sandbox for isolated environments.

​
Serializing Dependencies

​
Export Requirements

Generate a requirements.txt from script metadata: 
# Export dependencies
uv export --script notebook.py --no-hashes > requirements.txt
Creates:
requirements.txt
marimo==0.9.0
pandas>=2.0.0
plotly>=5.0.0
scikit-learn

​
Lock Files

For reproducible environments, use lock files: 
# Create lock file
uv lock --script notebook.py

# Install from lock file
uv sync --script notebook.py

​
Virtual Environments

​
Manual Virtual Environments

You can still use traditional virtual environments: 
# Create venv
python -m venv venv

# Activate
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

# Install marimo and dependencies
pip install marimo pandas plotly

# Run notebook
marimo edit notebook.py

​
Sandbox vs. Manual venvs

FeatureSandbox (--sandbox)Manual venv
SetupAutomaticManual
IsolationPer-notebookPer-project
PersistenceEphemeral (cached)Persistent
DependenciesFrom PEP 723 metadatarequirements.txt
SwitchingAutomaticManual activation
Best forNotebooks, scriptsProjects, apps

​
Environment Variables

​
Metadata Management

Control when marimo manages metadata: 
# Enable metadata management
export MARIMO_MANAGE_SCRIPT_METADATA=true
marimo edit notebook.py --sandbox
When enabled, marimo automatically:
  • Adds marimo to dependencies if missing
  • Updates requires-python based on current Python version
  • Keeps metadata in sync with your environment

​
Common Workflows

# Create notebook
marimo edit new_analysis.py

# Add dependencies via UI or:
uv add --script new_analysis.py pandas plotly

# Run in sandbox
marimo edit new_analysis.py --sandbox

# Dependencies are embedded in the .py file
git add notebook.py
git commit -m "Add analysis notebook"
git push

# Collaborator runs:
git pull
marimo edit notebook.py --sandbox
# Dependencies auto-install!

# Update a package version
uv add --script notebook.py "pandas>=2.1.0"

# Run with fresh install
marimo edit notebook.py --sandbox

# Export requirements
uv export --script notebook.py > requirements.txt

# Install in production venv
pip install -r requirements.txt

# Run without sandbox
marimo run notebook.py

​
Troubleshooting

Problem: marimo edit --sandbox fails with “uv not found”Solution: Install uv:
pip install uv
# or
curl -LsSf https://astral.sh/uv/install.sh | sh
Problem: marimo edit ./dir --sandbox failsSolution: Install sandbox extras:
pip install marimo[sandbox]
Problem: Dependency resolution errorsSolution:
# Check metadata syntax
uv tree --script notebook.py

# Try with specific Python version
marimo edit notebook.py --sandbox
Problem: First --sandbox run is slowSolution: This is normal - uv is creating a venv and installing packages. Subsequent runs use cached environments.Speed it up:
# Pre-compile bytecode
marimo edit notebook.py --sandbox
# (already done by default!)

​
Best Practices

1

Pin important versions

# /// script
# dependencies = [
#     "pandas>=2.0.0",      # Allow updates
#     "scikit-learn==1.3.0",  # Pin critical packages
# ]
# ///
2

Document package choices

# /// script
# dependencies = [
#     "pandas>=2.0.0",  # Requires 2.0 for new API
#     "plotly",          # Interactive visualizations
# ]
# ///
3

Keep dependencies minimal

Only include packages you actually import:
# Don't list transitive dependencies
# uv handles them automatically
4

Test in sandbox mode

# Verify clean installation
marimo edit notebook.py --sandbox

​
Comparison with Other Tools

Toolmarimo + uvpip + requirements.txtconda
Metadata locationIn notebook fileSeparate fileenvironment.yml
IsolationPer-notebookPer-environmentPer-environment
SpeedVery fast (uv)ModerateSlow
StandardPEP 723requirements.txtconda format
Version controlSingle fileMultiple filesMultiple files

​
Advanced Configuration

​
Editable Installs

For development, install packages in editable mode: 
# Add local package
uv add --script notebook.py -e ../my-package
Updates metadata: 
# /// script
# dependencies = [
#     "-e ../my-package",
# ]
# ///

​
Environment-Specific Dependencies

Use environment markers: 
# /// script
# dependencies = [
#     "pandas",
#     "pywin32; platform_system=='Windows'",
#     "uvloop; platform_system=='Linux'",
# ]
# ///

​
Next Steps

Creating Notebooks

Learn notebook structure and cells

Running Notebooks

Explore execution modes

Build docs developers (and LLMs) love

Get started for freeTalk to us