feat: add [tool.marimo.venv].path to specify a specific venv

[dmadisetti]

Introduces [tool.marimo.venv].path configuration option that allows users to specify a custom virtual environment for sandbox multi mode. This enables using predefined environments (conda, poetry, custom venvs) instead of ephemeral sandboxes.

Configuration

In your notebook's script metadata or pyproject.toml:

[tool.marimo.venv]
path = "path/to/venv"      # relative or absolute path
writable = true            # optional: allow marimo to install deps (default: false)

Behavior

editable	marimo installed?	Action
true	-	Installs marimo + IPC deps (pyzmq) into the venv
false	Yes	Uses venv as-is, warns if version mismatch
false	No	Injects PYTHONPATH for marimo (requires matching Python version)

Additionally, has some handling / logic for incompatible venvs:

Error Handling

• Invalid venv path: Clear error message if venv doesn't exist or has no Python interpreter
• Python version mismatch: When editable=false and marimo isn't installed, checks that venv Python matches server Python (required for binary deps like msgspec, pyzmq)
• Version mismatch warning: Logs warning if venv's marimo version differs from current

Supercedes #7624

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
marimo-docs	Ready	Preview, Comment	Jan 14, 2026 9:22pm

[akshayka]

It sounds like ephemeral sandboxes can use different Python versions than the server process, but configured venv's can't. Is that correct, and if so why the asymmetry?

[dmadisetti]

Let me know if the new comments address this