fix(config): resolve .env relative to the notebook when no pyproject.toml

[DevPranjal]

📝 Summary

Closes #10252

A notebook only loaded a neighbouring .env if a pyproject.toml existed above it. The issue reports this for sandboxed notebooks, but it isn't sandbox-specific: marimo edit ~/scratch/nb.py breaks the same way. Now it falls back to the notebook's own folder (nothing changes if pyproject.toml exists)

@dmadisetti

📋 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 - discussed in Automatic .env loading in sandbox mode #10252
• Any AI generated code has been reviewed line-by-line by the human PR author, who stands by it.

✅ 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 20, 2026 4:33pm

[github-actions]

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

[Copilot]

Pull request overview

Adjusts marimo’s project config resolution so .env defaults are anchored to the notebook directory when no pyproject.toml is found, addressing cases like standalone/sandboxed notebooks while preserving the existing “pyproject root wins” behavior.

Changes:

• Add a fallback root for resolving relative runtime.dotenv paths when pyproject.toml is absent.
• Add tests covering .env resolution without a pyproject.toml (file + directory start paths) and preference for the pyproject.toml root.
• Update configuration docs to reflect the new .env default behavior for standalone notebooks.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
marimo/_config/manager.py	Introduces _dotenv_root and uses it to resolve runtime.dotenv even when no pyproject.toml exists.
tests/_config/test_manager.py	Adds regression tests for dotenv path anchoring in no-pyproject and nested-notebook scenarios.
marimo/_config/config.py	Updates runtime config docs/comments to describe the new default .env behavior and resolution rules.
docs/guides/configuration/runtime_configuration.md	Documents .env default loading for standalone notebooks without a pyproject.toml.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[DevPranjal]

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

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (4)

marimo/_config/manager.py:633

• An explicit user setting runtime.dotenv = [] previously and naturally means “load no dotenv files,” but this now silently discards it and applies the new automatic .env default. That leaves users no global opt-out and can unexpectedly load a neighboring credentials file. A stale masked value is indistinguishable from an intentional empty list, so preserve [] or introduce an explicit migration/representation that does not redefine valid user configuration.

def _drop_hollow_dotenv(config: PartialMarimoConfig) -> PartialMarimoConfig:
    """Drop an empty `runtime.dotenv`, which is a masked value and not a choice."""
    # NB. Reading the configuration blanks runtime.dotenv by emptying the list,
    # and marimo 0.18 and earlier saved that masked copy straight back to disk,
    # so an empty list there means "hidden", not "load nothing". Keeping it

marimo/_config/manager.py:537

• This resolution is erased in real sessions. SessionImpl.create re-adds ScriptConfigManager(...).get_config() with the default hide_secrets=True (marimo/_session/session.py:110-112), which masks runtime.dotenv to []; that later override then wins even when the final kernel config is requested unmasked. Thus a PEP 723 runtime.dotenv still loads nothing, while these direct manager tests pass. Pass the unmasked value into the server-side config manager (or avoid the duplicate masked layer) and add a session-level regression test.

            marimo_config = ProjectConfigManager(
                self.filename
            )._resolve_dotenv(marimo_config)

marimo/_config/manager.py:356

• The PR description says nothing changes when a pyproject.toml exists, but this branch now rejects absolute paths outside the project and escaping relative paths that were previously supported. Existing projects can therefore stop loading configured environment files. Either preserve the prior project behavior in this focused fix, or explicitly document the breaking security hardening and migration in the PR/release notes.

This issue also appears in the following locations of the same file:

• line 535
• line 629

            if not candidate.resolve().is_relative_to(real_root):
                LOGGER.warning(
                    "Ignored a runtime.dotenv entry that resolves outside "
                    "the notebook or project directory. Move the .env file "
                    "next to the notebook or into the project, or set "

docs/guides/configuration/runtime_configuration.md:145

• This says paths must be relative, but the implementation accepts absolute paths that resolve inside the project; it enforces containment rather than relativity. The sentence also contains “must point be relative.” Describe the actual containment rule instead.

For security, a `dotenv` set in a `pyproject.toml` must point be relative to
the project directory, and paths that resolve outside the directory, including
symlinks, are ignored. To read a `.env` anywhere on your file system, set
`dotenv` in your [user configuration](index.md).