Skip to content

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.

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

Pranjal Gulatif23d6617bfd1
diff --git a/docs/guides/configuration/runtime_configuration.md b/docs/guides/configuration/runtime_configuration.md
index 146d96a806..e69bb0bbf0 100644
--- a/docs/guides/configuration/runtime_configuration.md
+++ b/docs/guides/configuration/runtime_configuration.md
@@ -132,11 +132,17 @@ pythonpath = ["project/src"]
marimo supports loading environment variables from `.env` files. This is useful for managing configuration that should not be committed to version control, such as API keys or database credentials.
-The `.env` next to your `pyproject.toml` is loaded by default. To configure multiple or a different location, you can specify them in your configuration:
+marimo loads the `.env` next to your `pyproject.toml` by default. A notebook with no `pyproject.toml`, such as a [sandboxed notebook](../package_management/sandboxes.md), loads the `.env` next to the notebook instead. marimo skips this default when the notebook is in your home directory. To load several files or a different location, list them in your configuration:
```toml title="pyproject.toml"
[tool.marimo.runtime]
dotenv = [".env", ".env.testing"]
```
+Relative paths resolve against the directory holding the `pyproject.toml`, or
+against the notebook's directory when not in a project.
+The same rule applies to a `dotenv` set in [script
+metadata](index.md#script-metadata-configuration). To load no `.env` at all,
+set `dotenv = []` in your `pyproject.toml` or script metadata.
+
Environment variables from your `dotenv` will be surfaced in the UI when creating databases.
diff --git a/marimo/_config/config.py b/marimo/_config/config.py
index a1b6486137..0762192a94 100644
--- a/marimo/_config/config.py
+++ b/marimo/_config/config.py
@@ -162,8 +162,10 @@ class RuntimeConfig(TypedDict):
`PYTHONPATH` environment variable, the directories will be included in
where Python will look for imported modules.
- `dotenv`: a list of paths to `.env` files to load.
- If the file does not exist, it will be silently ignored.
- The default is `[".env"]` if a pyproject.toml is found, otherwise `[]`.
+ If the file does not exist, it will be silently ignored. Relative
+ paths resolve against the directory holding the `pyproject.toml`,
+ or the notebook's directory when there is none. The default is
+ `[".env"]`.
- `default_sql_output`: the default output format for SQL queries. Can be one of:
`"auto"`, `"native"`, `"polars"`, `"lazy-polars"`, or `"pandas"`.
The default is `"auto"`.
@@ -797,8 +799,8 @@ DEFAULT_CONFIG: MarimoConfig = {
},
"formatting": {"line_length": 79},
"keymap": {"preset": "default", "overrides": {}},
- # dotenv's default value is set at runtime, depending on whether a
- # pyproject.toml is found.
+ # dotenv's default value is set at runtime, since it resolves relative to
+ # the pyproject.toml or the notebook's directory.
"runtime": {
"auto_instantiate": False,
"auto_reload": "off",
diff --git a/marimo/_config/manager.py b/marimo/_config/manager.py
index c5128e7ec1..5e07f458c5 100644
--- a/marimo/_config/manager.py
+++ b/marimo/_config/manager.py
@@ -170,10 +170,30 @@ class MarimoConfigManager(MarimoConfigReader):
)
return cast(PartialMarimoConfig, result)
+ def get_config_defaults(
+ self, *, hide_secrets: bool = True
+ ) -> PartialMarimoConfig:
+ """Get the defaults the partials compute, merged beneath the user configuration"""
+ result: MarimoConfig = cast(MarimoConfig, {})
+ for partial in (*self.partials, *self.security_partials):
+ result = merge_config(
+ result, partial.get_defaults(hide_secrets=hide_secrets)
+ )
+ return cast(PartialMarimoConfig, result)
+
def get_config(self, *, hide_secrets: bool = True) -> MarimoConfig:
"""Get the configuration, by merging the user configuration and the configuration overrides"""
+ # NB. Defaults go under the user configuration, overrides over it. A
+ # default a partial computes from the notebook location is not
+ # something anyone wrote, so it must lose to a value the user set.
return merge_config(
- self.get_user_config(hide_secrets=hide_secrets),
+ merge_config(
+ cast(
+ MarimoConfig,
+ self.get_config_defaults(hide_secrets=hide_secrets),
+ ),
+ self.get_user_config(hide_secrets=hide_secrets),
+ ),
self.get_config_overrides(hide_secrets=hide_secrets),
)
@@ -191,10 +211,21 @@ class MarimoConfigManager(MarimoConfigReader):
The new override is appended after the existing partials but before the
security partials, which the constructor keeps last so they always win.
"""
+ return self.with_partial(MarimoConfigReaderWithOverrides(overrides))
+
+ def with_partial(
+ self, partial: PartialMarimoConfigReader
+ ) -> MarimoConfigManager:
+ """Get a new config manager with the given partial reader layered on
+
+ Unlike `with_overrides`, the reader keeps answering `hide_secrets`
+ itself, so a masked read does not become the value an unmasked read
+ returns.
+ """
return MarimoConfigManager(
self.user_config_mgr,
*self.partials,
- MarimoConfigReaderWithOverrides(overrides),
+ partial,
*self.security_partials,
)
@@ -205,27 +236,69 @@ class PartialMarimoConfigReader:
def get_config(self, *, hide_secrets: bool = True) -> PartialMarimoConfig:
"""Get the configuration, as a partial configuration"""
+ def get_defaults(
+ self, *, hide_secrets: bool = True
+ ) -> PartialMarimoConfig:
+ """Get the values that apply when no configuration layer set them"""
+ del hide_secrets # no defaults, so nothing to mask
+ return {}
+
class ProjectConfigManager(PartialMarimoConfigReader):
"""Read the project configuration"""
def __init__(self, start_path: str) -> None:
+ self.start_path = start_path
self.pyproject_path = find_nearest_pyproject_toml(start_path)
+ @property
+ def _dotenv_root(self) -> Path:
+ """Directory that relative `dotenv` paths resolve against.
+
+ Standalone notebooks (such as sandboxed ones) have no
+ pyproject.toml to anchor on, so they fall back to the directory
+ holding the notebook.
+ """
+ if self.pyproject_path is not None:
+ return self.pyproject_path.parent
+ start_path = Path(self.start_path)
+ return start_path if start_path.is_dir() else start_path.parent
+
+ def get_defaults(
+ self, *, hide_secrets: bool = True
+ ) -> PartialMarimoConfig:
+ """Get the `.env` next to the project, loaded when no layer set `dotenv`"""
+ root = self._dotenv_root
+ if self.pyproject_path is None and _is_home_directory(root):
+ # NB. Without a pyproject.toml the anchor is wherever the notebook
+ # or `marimo edit` sits. For ~ that would load ~/.env and list its
+ # keys in the secrets panel, so the default is skipped there.
+ return {}
+ # NB. Emitted as a default, not from get_config(): get_config() is an
+ # override layer over the user configuration, so a path nobody wrote
+ # would outrank the user's own runtime.dotenv and would show up as a
+ # project override in the settings editor.
+ defaults = cast(
+ PartialMarimoConfig,
+ {"runtime": {"dotenv": [str((root / ".env").absolute())]}},
+ )
+ if hide_secrets:
+ return mask_secrets_partial(defaults)
+ return defaults
+
# It is safe to cache this config, as we only read from the pyproject.toml
# and never update it. If the user updates the pyproject.toml,
# it is ok to expect updates to be reflected after a server restart.
@lru_cache(maxsize=2) # noqa: B019
def get_config(self, *, hide_secrets: bool = True) -> PartialMarimoConfig:
try:
- if self.pyproject_path is None:
- return {}
- project_config = read_pyproject_marimo_config(self.pyproject_path)
+ project_config = (
+ read_pyproject_marimo_config(self.pyproject_path)
+ if self.pyproject_path is not None
+ else None
+ )
if project_config is None:
- # Some project configuration defaults (dotenv in particular)
- # are resolved at runtime, even in the absence of marimo
- # section in the pyproject.toml.
- project_config = cast(PartialMarimoConfig, {})
+ return {}
project_config = self._resolve_pythonpath(project_config)
project_config = self._resolve_dotenv(project_config)
project_config = self._resolve_custom_css(project_config)
@@ -272,19 +345,18 @@ class ProjectConfigManager(PartialMarimoConfigReader):
def _resolve_dotenv(
self, config: PartialMarimoConfig
) -> PartialMarimoConfig:
- if self.pyproject_path is None:
- return config
-
runtime = config.get("runtime", cast(RuntimeConfig, {}))
- dotenv = runtime.get("dotenv", [".env"])
+ if "dotenv" not in runtime:
+ # NB. The default is emitted by get_defaults() instead, which
+ # ranks below the user configuration.
+ return config
+ dotenv = runtime["dotenv"]
if not isinstance(dotenv, list):
return config
- resolved_dotenv = [
- str((self.pyproject_path.parent / path).absolute())
- for path in dotenv
- ]
+ root = self._dotenv_root
+ resolved_dotenv = [str((root / path).absolute()) for path in dotenv]
return {**config, "runtime": {**runtime, "dotenv": resolved_dotenv}}
def _resolve_custom_css(
@@ -431,6 +503,20 @@ class ScriptConfigManager(PartialMarimoConfigReader):
def __init__(self, filename: str | None) -> None:
self.filename = filename
+ def get_defaults(
+ self, *, hide_secrets: bool = True
+ ) -> PartialMarimoConfig:
+ """Get the `.env` next to the notebook, loaded when no layer set `dotenv`"""
+ # NB. In a directory workspace the project manager anchors on the
+ # directory marimo edit opened, not on the notebook a session runs.
+ # Script config already outranks project config, so the notebook's
+ # default outranks the workspace's the same way.
+ if self.filename is None:
+ return {}
+ return ProjectConfigManager(self.filename).get_defaults(
+ hide_secrets=hide_secrets
+ )
+
# It is safe to cache this config, as we only read from the script
# and never update it. If the user updates the script,
# it is ok to expect updates to be reflected after a server restart.
@@ -467,6 +553,11 @@ class ScriptConfigManager(PartialMarimoConfigReader):
)
if marimo_config is None:
return {}
+
+ marimo_config = ProjectConfigManager(
+ self.filename
+ )._resolve_dotenv(marimo_config)
+
# PEP 723 script metadata cannot anchor cache-signing trust.
marimo_config = strip_untrusted_config(marimo_config)
@@ -549,7 +640,7 @@ class UserConfigManager(MarimoConfigReader):
user_config = strip_untrusted_config(
user_config, is_user_layer=True
)
- return merge_default_config(user_config)
+ return merge_default_config(_drop_hollow_dotenv(user_config))
else:
LOGGER.debug("No config found; loading default settings.")
return DEFAULT_CONFIG
@@ -567,6 +658,26 @@ class MarimoConfigReaderWithOverrides(PartialMarimoConfigReader):
return self.override_config
+def _is_home_directory(path: Path) -> bool:
+ home = os.path.expanduser("~")
+ if home == "~":
+ return False
+ return os.path.realpath(path) == os.path.realpath(home)
+
+
+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
+ # would let a stale file suppress the .env next to the notebook.
+ runtime = config.get("runtime")
+ if runtime is None or runtime.get("dotenv") != []:
+ return config
+ without_dotenv = {k: v for k, v in runtime.items() if k != "dotenv"}
+ return {**config, "runtime": cast(RuntimeConfig, without_dotenv)}
+
+
def _drop_none_values(d: dict[str, Any]) -> None:
"""Recursively remove keys whose value is None, in place."""
for key in list(d):
diff --git a/marimo/_session/session.py b/marimo/_session/session.py
index 391668fa8b..2acd068076 100644
--- a/marimo/_session/session.py
+++ b/marimo/_session/session.py
@@ -116,10 +116,12 @@ class SessionImpl(Session):
"""
Create a new session.
"""
- # Inherit config from the session manager
- # and override with any script-level config
- config_manager = config_manager.with_overrides(
- ScriptConfigManager(app_file_manager.path).get_config()
+ # Inherit config from the session manager and override with any
+ # script-level config. The reader is layered on as-is: snapshotting
+ # its masked get_config() would turn runtime.dotenv into [] and that
+ # empty list would then win the merge the kernel reads unmasked.
+ config_manager = config_manager.with_partial(
+ ScriptConfigManager(app_file_manager.path)
)
configs = app_file_manager.app.cell_manager.config_map()
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index 68d555e3b6..962f17ed21 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -4759,17 +4759,18 @@ components:
\ environment variable, the directories will be included in\n where\
\ Python will look for imported modules.\n - `dotenv`: a list of paths\
\ to `.env` files to load.\n If the file does not exist, it will be\
- \ silently ignored.\n The default is `[\".env\"]` if a pyproject.toml\
- \ is found, otherwise `[]`.\n - `default_sql_output`: the default output\
- \ format for SQL queries. Can be one of:\n `\"auto\"`, `\"native\"\
- `, `\"polars\"`, `\"lazy-polars\"`, or `\"pandas\"`.\n The default\
- \ is `\"auto\"`.\n - `default_auto_download`: an Optional list of export\
- \ types to automatically snapshot your notebook as:\n `html`, `markdown`,\
- \ `ipynb`.\n The default is None.\n - `default_csv_encoding`: the\
- \ default encoding for CSV exports.\n The default is `\"utf-8\"`.\n\
- \ - `show_tracebacks`: if `True`, show detailed error tracebacks in run\
- \ mode.\n When enabled, exceptions will display a clickable toast that\
- \ opens a modal with the full traceback.\n The default is `False`."
+ \ silently ignored. Relative\n paths resolve against the directory\
+ \ holding the `pyproject.toml`,\n or the notebook's directory when\
+ \ there is none. The default is\n `[\".env\"]`.\n - `default_sql_output`:\
+ \ the default output format for SQL queries. Can be one of:\n `\"auto\"\
+ `, `\"native\"`, `\"polars\"`, `\"lazy-polars\"`, or `\"pandas\"`.\n \
+ \ The default is `\"auto\"`.\n - `default_auto_download`: an Optional\
+ \ list of export types to automatically snapshot your notebook as:\n \
+ \ `html`, `markdown`, `ipynb`.\n The default is None.\n - `default_csv_encoding`:\
+ \ the default encoding for CSV exports.\n The default is `\"utf-8\"\
+ `.\n - `show_tracebacks`: if `True`, show detailed error tracebacks in\
+ \ run mode.\n When enabled, exceptions will display a clickable toast\
+ \ that opens a modal with the full traceback.\n The default is `False`."
properties:
auto_instantiate:
type: boolean
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index 3bc0351bcf..875c0486e2 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -6730,8 +6730,10 @@ export interface components {
* `PYTHONPATH` environment variable, the directories will be included in
* where Python will look for imported modules.
* - `dotenv`: a list of paths to `.env` files to load.
- * If the file does not exist, it will be silently ignored.
- * The default is `[".env"]` if a pyproject.toml is found, otherwise `[]`.
+ * If the file does not exist, it will be silently ignored. Relative
+ * paths resolve against the directory holding the `pyproject.toml`,
+ * or the notebook's directory when there is none. The default is
+ * `[".env"]`.
* - `default_sql_output`: the default output format for SQL queries. Can be one of:
* `"auto"`, `"native"`, `"polars"`, `"lazy-polars"`, or `"pandas"`.
* The default is `"auto"`.
diff --git a/tests/_config/test_manager.py b/tests/_config/test_manager.py
index 4ec8b1b0ca..9b6a295cde 100644
--- a/tests/_config/test_manager.py
+++ b/tests/_config/test_manager.py
@@ -214,6 +214,28 @@ def test_save_config_with_none_does_not_raise(tmp_path: Path) -> None:
assert "be terse" in contents
+def test_user_config_drops_hollow_dotenv(tmp_path: Path) -> None:
+ """An empty runtime.dotenv on disk is a masked value, so it is ignored."""
+ config_path = tmp_path / "marimo.toml"
+ config_path.write_text("[runtime]\ndotenv = []\n")
+ manager = UserConfigManager()
+ manager.get_config_path = lambda: str(config_path) # type: ignore[method-assign]
+
+ config = manager.get_config(hide_secrets=False)
+ assert "dotenv" not in config["runtime"]
+
+
+def test_user_config_keeps_populated_dotenv(tmp_path: Path) -> None:
+ config_path = tmp_path / "marimo.toml"
+ dotenv = tmp_path / ".env.user"
+ config_path.write_text(f'[runtime]\ndotenv = ["{dotenv.as_posix()}"]\n')
+ manager = UserConfigManager()
+ manager.get_config_path = lambda: str(config_path) # type: ignore[method-assign]
+
+ config = manager.get_config(hide_secrets=False)
+ assert config["runtime"]["dotenv"] == [dotenv.as_posix()]
+
+
def test_drop_none_values_strips_nested_none() -> None:
from marimo._config.manager import _drop_none_values
@@ -355,6 +377,355 @@ def test_project_config_default_dotenv(tmp_path: Path) -> None:
assert config["runtime"]["dotenv"] == [str(tmp_path / ".env")]
+def test_project_config_dotenv_without_pyproject(tmp_path: Path) -> None:
+ # Standalone notebooks (e.g. PEP 723 sandboxes) have no pyproject.toml to
+ # anchor on, so the dotenv default resolves next to the notebook.
+ notebook_path = tmp_path / "notebook.py"
+ notebook_path.write_text("import marimo as mo")
+
+ manager = get_default_config_manager(current_path=str(notebook_path))
+ config = manager.get_config(hide_secrets=False)
+ assert config["runtime"]["dotenv"] == [str(tmp_path / ".env")]
+
+
+def test_project_config_dotenv_without_pyproject_directory(
+ tmp_path: Path,
+) -> None:
+ manager = get_default_config_manager(current_path=str(tmp_path))
+ config = manager.get_config(hide_secrets=False)
+ assert config["runtime"]["dotenv"] == [str(tmp_path / ".env")]
+
+
+def test_default_dotenv_is_masked_with_the_other_secrets(
+ tmp_path: Path,
+) -> None:
+ # The computed default is a runtime.dotenv entry like any other, so a
+ # masked read must hide it too.
+ notebook_path = tmp_path / "notebook.py"
+ notebook_path.write_text("import marimo as mo")
+
+ manager = get_default_config_manager(current_path=str(notebook_path))
+ assert manager.get_config()["runtime"]["dotenv"] == []
+ assert manager.get_config(hide_secrets=False)["runtime"]["dotenv"] == [
+ str(tmp_path / ".env")
+ ]
+
+
+def test_project_config_empty_dotenv_opts_out(tmp_path: Path) -> None:
+ # A user-level [] is dropped as a masked leftover, but a pyproject.toml is
+ # never written back masked, so its [] is a deliberate "load nothing".
+ notebook_path = _write_dotenv_project(tmp_path, "")
+ (notebook_path.parent / ".env").write_text("KEY=value")
+
+ manager = get_default_config_manager(current_path=str(notebook_path))
+ assert manager.get_config(hide_secrets=False)["runtime"]["dotenv"] == []
+
+
+def test_default_dotenv_skips_the_home_directory(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ # `marimo edit ~/nb.py`, or `marimo edit` run from ~, would otherwise load
+ # ~/.env and list its keys in the secrets panel.
+ _isolate_user_config(monkeypatch, tmp_path, "")
+ home = tmp_path / "home"
+ home.mkdir()
+ (home / ".env").write_text("KEY=value")
+ _set_home(monkeypatch, home)
+ notebook_path = home / "nb.py"
+ notebook_path.write_text("import marimo as mo")
+
+ for start_path in (notebook_path, home):
+ manager = get_default_config_manager(current_path=str(start_path))
+ config = manager.get_config(hide_secrets=False)
+ assert "dotenv" not in config["runtime"]
+
+
+def test_default_dotenv_applies_to_a_pyproject_in_the_home_directory(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ # A pyproject.toml in ~ is a deliberate project root, so the pre-existing
+ # default stays.
+ _isolate_user_config(monkeypatch, tmp_path, "")
+ home = tmp_path / "home"
+ home.mkdir()
+ (home / "pyproject.toml").write_text("")
+ _set_home(monkeypatch, home)
+ notebook_path = home / "nb.py"
+ notebook_path.write_text("import marimo as mo")
+
+ manager = get_default_config_manager(current_path=str(notebook_path))
+ config = manager.get_config(hide_secrets=False)
+ assert config["runtime"]["dotenv"] == [str(home / ".env")]
+
+
+def test_explicit_dotenv_resolves_in_the_home_directory(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ _isolate_user_config(monkeypatch, tmp_path, "")
+ home = tmp_path / "home"
+ home.mkdir()
+ _set_home(monkeypatch, home)
+ notebook_path = home / "nb.py"
+ notebook_path.write_text(
+ textwrap.dedent(
+ """
+ # /// script
+ # [tool.marimo.runtime]
+ # dotenv = [".env"]
+ # ///
+ import marimo as mo
+ """
+ )
+ )
+
+ config = ScriptConfigManager(str(notebook_path)).get_config(
+ hide_secrets=False
+ )
+ assert config["runtime"]["dotenv"] == [str(home / ".env")]
+
+
+def test_directory_workspace_dotenv_anchors_on_the_notebook(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ # `marimo edit repo/` reads project config from repo/, but each session
+ # layers the notebook's script config on top. The notebook-level default
+ # follows the same precedence, so repo/sub/app.py gets repo/sub/.env.
+ _isolate_user_config(monkeypatch, tmp_path, "")
+ repo = tmp_path / "repo"
+ sub = repo / "sub"
+ sub.mkdir(parents=True)
+ (repo / ".env").write_text("KEY=repo")
+ (sub / ".env").write_text("KEY=sub")
+ notebook_path = sub / "app.py"
+ notebook_path.write_text("import marimo as mo")
+
+ workspace = get_default_config_manager(current_path=str(repo))
+ session = workspace.with_partial(ScriptConfigManager(str(notebook_path)))
+ config = session.get_config(hide_secrets=False)
+ assert config["runtime"]["dotenv"] == [str(sub / ".env")]
+ assert "runtime" not in session.get_config_overrides(hide_secrets=False)
+
+
+def test_directory_workspace_dotenv_keeps_the_pyproject_root(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ _isolate_user_config(monkeypatch, tmp_path, "")
+ repo = tmp_path / "repo"
+ sub = repo / "sub"
+ sub.mkdir(parents=True)
+ (repo / "pyproject.toml").write_text("")
+ notebook_path = sub / "app.py"
+ notebook_path.write_text("import marimo as mo")
+
+ workspace = get_default_config_manager(current_path=str(repo))
+ session = workspace.with_partial(ScriptConfigManager(str(notebook_path)))
+ config = session.get_config(hide_secrets=False)
+ assert config["runtime"]["dotenv"] == [str(repo / ".env")]
+
+
+def test_directory_workspace_dotenv_falls_back_to_the_workspace_root(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ # A new, unsaved notebook has no path to anchor on.
+ _isolate_user_config(monkeypatch, tmp_path, "")
+ repo = tmp_path / "repo"
+ repo.mkdir()
+
+ workspace = get_default_config_manager(current_path=str(repo))
+ session = workspace.with_partial(ScriptConfigManager(None))
+ config = session.get_config(hide_secrets=False)
+ assert config["runtime"]["dotenv"] == [str(repo / ".env")]
+
+
+def test_project_config_dotenv_prefers_pyproject_root(tmp_path: Path) -> None:
+ # When a pyproject.toml exists, it stays the anchor even if the notebook
+ # lives in a subdirectory.
+ (tmp_path / "pyproject.toml").write_text("")
+ notebooks = tmp_path / "notebooks"
+ notebooks.mkdir()
+ notebook_path = notebooks / "notebook.py"
+ notebook_path.write_text("import marimo as mo")
+
+ manager = get_default_config_manager(current_path=str(notebook_path))
+ config = manager.get_config(hide_secrets=False)
+ assert config["runtime"]["dotenv"] == [str(tmp_path / ".env")]
+
+
+def _write_dotenv_project(tmp_path: Path, dotenv_entries: str) -> Path:
+ """Write a project with runtime.dotenv set, return its notebook path."""
+ project = tmp_path / "project"
+ project.mkdir(exist_ok=True)
+ (project / "pyproject.toml").write_text(
+ textwrap.dedent(
+ f"""
+ [tool.marimo.runtime]
+ dotenv = [{dotenv_entries}]
+ """
+ )
+ )
+ notebook_path = project / "notebook.py"
+ notebook_path.write_text("import marimo as mo")
+ return notebook_path
+
+
+def test_project_config_dotenv_allows_subdirectory(tmp_path: Path) -> None:
+ notebook_path = _write_dotenv_project(tmp_path, '"config/.env"')
+ config_dir = notebook_path.parent / "config"
+ config_dir.mkdir()
+ (config_dir / ".env").write_text("KEY=value")
+
+ manager = get_default_config_manager(current_path=str(notebook_path))
+ config = manager.get_config(hide_secrets=False)
+ assert config["runtime"]["dotenv"] == [str(config_dir / ".env")]
+
+
+def _isolate_user_config(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, contents: str
+) -> None:
+ """Point the user configuration at a temporary marimo.toml."""
+ config_path = tmp_path / "user" / "marimo.toml"
+ config_path.parent.mkdir(parents=True, exist_ok=True)
+ config_path.write_text(textwrap.dedent(contents))
+ monkeypatch.setattr(
+ "marimo._config.manager.get_or_create_user_config_path",
+ lambda: str(config_path),
+ )
+
+
+def _set_home(monkeypatch: pytest.MonkeyPatch, home: Path) -> None:
+ """Point `~` at a temporary directory on every platform."""
+ # NB. os.path.expanduser reads HOME on POSIX and USERPROFILE on Windows.
+ monkeypatch.setenv("HOME", str(home))
+ monkeypatch.setenv("USERPROFILE", str(home))
+
+
+def _write_notebook(tmp_path: Path, *, with_pyproject: bool) -> Path:
+ """Write a notebook, under a pyproject.toml that says nothing about dotenv."""
+ project = tmp_path / "project"
+ project.mkdir()
+ if with_pyproject:
+ (project / "pyproject.toml").write_text(
+ textwrap.dedent(
+ """
+ [tool.marimo.formatting]
+ line_length = 100
+ """
+ )
+ )
+ notebook_path = project / "notebook.py"
+ notebook_path.write_text("import marimo as mo")
+ return notebook_path
+
+
[email protected]("with_pyproject", [True, False])
+def test_user_config_dotenv_beats_the_default(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, with_pyproject: bool
+) -> None:
+ # The default is resolved from the notebook location, so it must not
+ # outrank a dotenv the user wrote in their own configuration.
+ outside = tmp_path / "outside" / ".env"
+ outside.parent.mkdir()
+ outside.write_text("KEY=value")
+ _isolate_user_config(
+ monkeypatch,
+ tmp_path,
+ f"""
+ [runtime]
+ dotenv = ["{outside.as_posix()}"]
+ """,
+ )
+ notebook_path = _write_notebook(tmp_path, with_pyproject=with_pyproject)
+
+ manager = get_default_config_manager(current_path=str(notebook_path))
+ config = manager.get_config(hide_secrets=False)
+ assert config["runtime"]["dotenv"] == [outside.as_posix()]
+
+
[email protected]("with_pyproject", [True, False])
+def test_default_dotenv_applies_with_an_empty_user_config(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, with_pyproject: bool
+) -> None:
+ _isolate_user_config(monkeypatch, tmp_path, "")
+ notebook_path = _write_notebook(tmp_path, with_pyproject=with_pyproject)
+
+ manager = get_default_config_manager(current_path=str(notebook_path))
+ config = manager.get_config(hide_secrets=False)
+ assert config["runtime"]["dotenv"] == [str(notebook_path.parent / ".env")]
+
+
+def test_default_dotenv_applies_over_a_hollow_user_dotenv(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ # marimo 0.18 and earlier wrote the masked (emptied) dotenv back to disk.
+ _isolate_user_config(
+ monkeypatch,
+ tmp_path,
+ """
+ [runtime]
+ dotenv = []
+ """,
+ )
+ notebook_path = _write_notebook(tmp_path, with_pyproject=False)
+
+ manager = get_default_config_manager(current_path=str(notebook_path))
+ config = manager.get_config(hide_secrets=False)
+ assert config["runtime"]["dotenv"] == [str(notebook_path.parent / ".env")]
+
+
+def test_project_dotenv_beats_user_config(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ user_env = tmp_path / "user" / ".env"
+ user_env.parent.mkdir(exist_ok=True)
+ user_env.write_text("KEY=value")
+ _isolate_user_config(
+ monkeypatch,
+ tmp_path,
+ f"""
+ [runtime]
+ dotenv = ["{user_env.as_posix()}"]
+ """,
+ )
+ notebook_path = _write_dotenv_project(tmp_path, '".env"')
+
+ manager = get_default_config_manager(current_path=str(notebook_path))
+ config = manager.get_config(hide_secrets=False)
+ assert config["runtime"]["dotenv"] == [str(notebook_path.parent / ".env")]
+
+
+def test_project_config_dotenv_keeps_absolute_and_parent_paths(
+ tmp_path: Path,
+) -> None:
+ # Configs such as dotenv = ["../shared/.env"] predate this anchoring, so
+ # entries leaving the project directory still resolve.
+ shared = tmp_path / "shared" / ".env"
+ notebook_path = _write_dotenv_project(
+ tmp_path, f'".env", "../shared/.env", "{shared.as_posix()}"'
+ )
+
+ manager = get_default_config_manager(current_path=str(notebook_path))
+ config = manager.get_config(hide_secrets=False)
+ assert config["runtime"]["dotenv"] == [
+ str(notebook_path.parent / ".env"),
+ str(notebook_path.parent / "../shared/.env"),
+ str(shared),
+ ]
+
+
[email protected]("with_pyproject", [True, False])
+def test_default_dotenv_is_not_a_config_override(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, with_pyproject: bool
+) -> None:
+ # The editor greys out settings reported here, so a default nobody wrote
+ # must not appear.
+ _isolate_user_config(monkeypatch, tmp_path, "")
+ notebook_path = _write_notebook(tmp_path, with_pyproject=with_pyproject)
+
+ manager = get_default_config_manager(current_path=str(notebook_path))
+ overrides = manager.get_config_overrides(hide_secrets=False)
+ assert "runtime" not in overrides
+
+
def test_project_config_manager_with_script_metadata(tmp_path: Path) -> None:
# Create a notebook file with script metadata
notebook_path = tmp_path / "notebook.py"
@@ -387,7 +758,10 @@ def test_project_config_manager_with_script_metadata(tmp_path: Path) -> None:
manager = get_default_config_manager(current_path=str(notebook_path))
config = manager.get_config_overrides(hide_secrets=False)
- # Verify that script metadata takes precedence over pyproject.toml
+ # Verify that script metadata takes precedence over pyproject.toml.
+ # runtime.dotenv is absent: neither file sets it, and the default the
+ # project computes is not an override, so the editor does not grey the
+ # setting out.
assert config == {
"formatting": {"line_length": 79}, # From script metadata
"save": {
@@ -395,9 +769,6 @@ def test_project_config_manager_with_script_metadata(tmp_path: Path) -> None:
"format_on_save": True, # From pyproject.toml
"autosave": "after_delay", # From pyproject.toml
},
- "runtime": {
- "dotenv": [str(tmp_path / ".env")],
- },
}
@@ -434,6 +805,62 @@ def test_script_config_manager_with_metadata(tmp_path: Path) -> None:
}
+def test_script_config_manager_dotenv_anchors_on_project(
+ tmp_path: Path,
+) -> None:
+ # Script metadata resolves relative dotenv paths like the pyproject.toml
+ # does: against the project directory, with absolute entries kept.
+ project = tmp_path / "project"
+ project.mkdir()
+ (project / "pyproject.toml").touch()
+ notebooks = project / "notebooks"
+ notebooks.mkdir()
+ shared = tmp_path / "shared" / ".env"
+ notebook_path = notebooks / "notebook.py"
+ notebook_content = f'''
+ # /// script
+ # [tool.marimo.runtime]
+ # dotenv = [".env", "{shared.as_posix()}"]
+ # ///
+ import marimo as mo
+ '''
+ notebook_path.write_text(textwrap.dedent(notebook_content))
+
+ config = ScriptConfigManager(str(notebook_path)).get_config(
+ hide_secrets=False
+ )
+
+ assert config["runtime"]["dotenv"] == [
+ str(project / ".env"),
+ str(shared),
+ ]
+
+
+def test_script_config_manager_dotenv_anchors_on_standalone_notebook(
+ tmp_path: Path,
+) -> None:
+ notebook_dir = tmp_path / "notebook"
+ notebook_dir.mkdir()
+ notebook_path = notebook_dir / "notebook.py"
+ notebook_content = """
+ # /// script
+ # [tool.marimo.runtime]
+ # dotenv = [".env", "../shared/.env"]
+ # ///
+ import marimo as mo
+ """
+ notebook_path.write_text(textwrap.dedent(notebook_content))
+
+ config = ScriptConfigManager(str(notebook_path)).get_config(
+ hide_secrets=False
+ )
+
+ assert config["runtime"]["dotenv"] == [
+ str(notebook_dir / ".env"),
+ str(notebook_dir / "../shared/.env"),
+ ]
+
+
def test_script_config_manager_ignores_file_browser(tmp_path: Path) -> None:
notebook_path = tmp_path / "notebook.py"
notebook_content = """
diff --git a/tests/_server/test_sessions.py b/tests/_server/test_sessions.py
index 5c62763968..2599d27b86 100644
--- a/tests/_server/test_sessions.py
+++ b/tests/_server/test_sessions.py
@@ -1120,6 +1120,52 @@ async def test_session_with_script_config_overrides(
session.close()
+async def test_session_script_dotenv_reaches_the_kernel_config(
+ tmp_path: Path,
+) -> None:
+ # runtime.dotenv is masked to [] when read with secrets hidden. If the
+ # session layered that masked snapshot on as an override, the empty list
+ # would win the unmasked merge the kernel reads, so a script-level dotenv
+ # would load nothing.
+ session_consumer = MagicMock()
+ session_consumer.connection_state.return_value = ConnectionState.OPEN
+ tmp_file = tmp_path / "nb.py"
+ tmp_file.write_text(
+ dedent(
+ """
+ # /// script
+ # [tool.marimo.runtime]
+ # dotenv = [".env", ".env.local"]
+ # ///
+ """
+ )
+ )
+ session = await SessionImpl.create(
+ initialization_id="test_id",
+ session_consumer=session_consumer,
+ mode=SessionMode.RUN,
+ app_metadata=app_metadata,
+ app_file_manager=AppFileManager(filename=str(tmp_file)),
+ config_manager=get_default_config_manager(current_path=str(tmp_file)),
+ virtual_file_storage="in_memory",
+ redirect_console_to_browser=False,
+ ttl_seconds=None,
+ auto_instantiate=True,
+ )
+ try:
+ kernel_config = session._kernel_manager.config_manager.get_config(
+ hide_secrets=False
+ )
+ assert kernel_config["runtime"]["dotenv"] == [
+ str(tmp_path / ".env"),
+ str(tmp_path / ".env.local"),
+ ]
+ masked = session.config_manager.get_config()
+ assert masked["runtime"]["dotenv"] == []
+ finally:
+ session.close()
+
+
async def test_caching_extension_respects_mode_and_config() -> None:
"""Test caching enablement and mode across edit/run sessions."""
from marimo._session.extensions.extensions import (
diff --git a/tests/_session/app_host/test_app_host.py b/tests/_session/app_host/test_app_host.py
index 138100be22..0dcbe20248 100644
--- a/tests/_session/app_host/test_app_host.py
+++ b/tests/_session/app_host/test_app_host.py
@@ -373,7 +373,7 @@ class TestAppHostMultipleClients:
),
),
config_manager=Mock(
- with_overrides=Mock(
+ with_partial=Mock(
return_value=Mock(
get_config=Mock(return_value=DEFAULT_CONFIG)
)