fix: force uv package manager unless a venv is configured

[volgar1x]

📝 Summary

📋 Pre-Review Checklist

• For large changes, or changes that affect the public API: this change was discussed or approved through an issue, on Discord, or the community discussions (Please provide a link if applicable).
• Any AI generated code has been reviewed line-by-line by the human PR author, who stands by it.
• Video or media evidence is provided for any visual changes (optional).

✅ Merge Checklist

• I have read the contributor guidelines.
• Documentation has been updated where applicable, including docstrings for API changes.
• Tests have been added for the changes made.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview	Aug 14, 2026 1:46pm

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[volgar1x]

I have read the CLA Document and I hereby sign the CLA

[mscolnick]

@cubic-dev-ai

[cubic-dev-ai]

@cubic-dev-ai

@mscolnick I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

2 issues found across 3 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="marimo/_server/start.py">

<violation number="1" location="marimo/_server/start.py:286">
P2: The PR's stated intent is to force the uv package manager unless a venv is configured, but the new guard only does so for `SandboxMode.MULTI` without a venv path. Previously the override applied whenever `MANAGE_SCRIPT_METADATA` was set, which also covers single-file sandbox (`sandbox.py` sets `MARIMO_MANAGE_SCRIPT_METADATA=true`) and Docker runs (`run_docker.py`). In those paths the uv override no longer applies. Confirm this narrowing is intended for non-MULTI modes; if not, keep the override when `GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA` is true while still respecting the venv check.</violation>

<violation number="2" location="marimo/_server/start.py:286">
P2: When a project configures a venv with `writable=true` (the VenvConfig contract states writable means marimo will manage script metadata), this condition keys only off `path` and skips setting `GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA`, so the server-side metadata features stay disabled even though the kernel is writable. `marimo/_session/managers/ipc.py` still sets the kernel-level `MARIMO_MANAGE_SCRIPT_METADATA` env var for a writable configured venv, but server-side code gates on the global (`packages.py:66,115,171` update the script header on install/uninstall; `file_manager.py:234` generates the header for new .py files). Before this PR, cli.py set the global to True for all MULTI-sandbox edit sessions, including configured-venv ones, so this is a regression for the writable-venv case: the kernel manages metadata while the server does not.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant CLI as CLI (marimo edit)
    participant ConfigMgr as MarimoConfigManager
    participant Server as Server (start.py)
    participant Settings as GLOBAL_SETTINGS
    participant Env as Environment Variables

    Note over CLI,Env: Sandboxed Notebook Startup Flow

    CLI->>CLI: Parse args (sandbox mode)
    alt Sandbox mode enabled
        CLI->>ConfigMgr: Check venv config
    end

    CLI->>Server: Call start() with sandbox_mode
    Server->>ConfigMgr: Access venv config
    ConfigMgr-->>Server: venv_config (dict)

    alt SandboxMode.MULTI and no venv path configured
        Server->>Env: Set MARIMO_MANAGE_SCRIPT_METADATA=true
        Server->>Settings: Set MANAGE_SCRIPT_METADATA=True
        Server->>ConfigMgr: with_overrides({uv metadata config})
        ConfigMgr-->>Server: Updated config with uv settings
    else Venv configured or single sandbox mode
        Server->>Settings: Keep MANAGE_SCRIPT_METADATA=False
        Note over Server,Settings: Script metadata managed by user's venv
    end

    Server->>Server: Continue server startup with effective config

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The PR's stated intent is to force the uv package manager unless a venv is configured, but the new guard only does so for SandboxMode.MULTI without a venv path. Previously the override applied whenever MANAGE_SCRIPT_METADATA was set, which also covers single-file sandbox (sandbox.py sets MARIMO_MANAGE_SCRIPT_METADATA=true) and Docker runs (run_docker.py). In those paths the uv override no longer applies. Confirm this narrowing is intended for non-MULTI modes; if not, keep the override when GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA is true while still respecting the venv check.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At marimo/_server/start.py, line 286:

<comment>The PR's stated intent is to force the uv package manager unless a venv is configured, but the new guard only does so for `SandboxMode.MULTI` without a venv path. Previously the override applied whenever `MANAGE_SCRIPT_METADATA` was set, which also covers single-file sandbox (`sandbox.py` sets `MARIMO_MANAGE_SCRIPT_METADATA=true`) and Docker runs (`run_docker.py`). In those paths the uv override no longer applies. Confirm this narrowing is intended for non-MULTI modes; if not, keep the override when `GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA` is true while still respecting the venv check.</comment>

<file context>
@@ -282,7 +282,10 @@ def start(
 
-    if GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA:
+    venv_config = config_reader.venv
+    if sandbox_mode is SandboxMode.MULTI and not venv_config.get("path"):
+        os.environ["MARIMO_MANAGE_SCRIPT_METADATA"] = "true"
+        GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA = True
</file context>

[cubic-dev-ai]

P2: When a project configures a venv with writable=true (the VenvConfig contract states writable means marimo will manage script metadata), this condition keys only off path and skips setting GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA, so the server-side metadata features stay disabled even though the kernel is writable. marimo/_session/managers/ipc.py still sets the kernel-level MARIMO_MANAGE_SCRIPT_METADATA env var for a writable configured venv, but server-side code gates on the global (packages.py:66,115,171 update the script header on install/uninstall; file_manager.py:234 generates the header for new .py files). Before this PR, cli.py set the global to True for all MULTI-sandbox edit sessions, including configured-venv ones, so this is a regression for the writable-venv case: the kernel manages metadata while the server does not.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At marimo/_server/start.py, line 286:

<comment>When a project configures a venv with `writable=true` (the VenvConfig contract states writable means marimo will manage script metadata), this condition keys only off `path` and skips setting `GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA`, so the server-side metadata features stay disabled even though the kernel is writable. `marimo/_session/managers/ipc.py` still sets the kernel-level `MARIMO_MANAGE_SCRIPT_METADATA` env var for a writable configured venv, but server-side code gates on the global (`packages.py:66,115,171` update the script header on install/uninstall; `file_manager.py:234` generates the header for new .py files). Before this PR, cli.py set the global to True for all MULTI-sandbox edit sessions, including configured-venv ones, so this is a regression for the writable-venv case: the kernel manages metadata while the server does not.</comment>

<file context>
@@ -282,7 +282,10 @@ def start(
 
-    if GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA:
+    venv_config = config_reader.venv
+    if sandbox_mode is SandboxMode.MULTI and not venv_config.get("path"):
+        os.environ["MARIMO_MANAGE_SCRIPT_METADATA"] = "true"
+        GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA = True
</file context>

[Light2Dark]

@volgar1x, this might have been discussed elsewhere or links to some issue? Would you mind filling out the PR description?