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.

Add a msgspec Struct schema for user configs (#11268)

Martha Cryan9264d809613c
diff --git a/marimo/_config/config.py b/marimo/_config/config.py
index 725cb2ce21..17939c81ee 100644
--- a/marimo/_config/config.py
+++ b/marimo/_config/config.py
@@ -1,11 +1,23 @@
# Copyright 2026 Marimo. All rights reserved.
+# Same-name aliases explicitly re-export types for strict type checking.
+# ruff: noqa: PLC0414
from __future__ import annotations
-import os
import sys
from dataclasses import dataclass
-from marimo._config.packages import infer_package_manager
+from marimo._config.config_schema import MarimoConfig as MarimoConfigSchema
+from marimo._config.types import (
+ CacheVerification as CacheVerification,
+ CopilotMode as CopilotMode,
+ ExecutionType as ExecutionType,
+ ExportType as ExportType,
+ OnCellChangeType as OnCellChangeType,
+ SqlOutputType as SqlOutputType,
+ StoreKey as StoreKey,
+ Theme as Theme,
+ WidthType as WidthType,
+)
from marimo._config.utils import deep_copy
if sys.version_info >= (3, 11):
@@ -94,10 +106,6 @@ class KeymapConfig(TypedDict):
destructive_delete: NotRequired[bool]
-OnCellChangeType = Literal["lazy", "autorun"]
-ExecutionType = Literal["relaxed", "strict"]
-
-
@mddoc
@dataclass
class VenvConfig(TypedDict, total=False):
@@ -118,15 +126,6 @@ class VenvConfig(TypedDict, total=False):
writable: bool
-# TODO(akshayka): remove normal, migrate to compact
-# normal == compact
-WidthType = Literal["normal", "compact", "medium", "full", "columns"]
-Theme = Literal["light", "dark", "system"]
-ExportType = Literal["html", "markdown", "ipynb"]
-SqlOutputType = Literal["polars", "lazy-polars", "pandas", "native", "auto"]
-StoreKey = Literal["file", "redis", "rest", "tiered"]
-
-
@mddoc
@dataclass
class RuntimeConfig(TypedDict):
@@ -281,9 +280,6 @@ class PackageManagementConfig(TypedDict):
manager: Literal["pip", "rye", "uv", "poetry", "pixi"]
-CopilotMode = Literal["ask", "manual", "agent", "code_mode"]
-
-
@mddoc
@dataclass
class AiModelConfig(TypedDict):
@@ -630,8 +626,6 @@ class StoreConfig(TypedDict, total=False):
# One store, or a list composed into a TieredStore.
CacheStoreConfig = list[StoreConfig] | StoreConfig
-CacheVerification = Literal["off", "on", "strict"]
-
class CacheConfig(TypedDict, total=False):
"""Configuration for caching.
@@ -779,86 +773,9 @@ class PartialMarimoConfig(TypedDict, total=False):
signing: NotRequired[SigningConfig]
-DEFAULT_CONFIG: MarimoConfig = {
- "completion": {
- "activate_on_typing": True,
- "signature_hint_on_typing": False,
- "copilot": False,
- "auto_close_pairs": True,
- },
- "display": {
- "theme": "light",
- "code_editor_font_size": 14,
- "cell_output": "below",
- "default_width": "medium",
- "dataframes": "rich",
- "default_table_page_size": 10,
- "default_table_max_columns": 50,
- "reference_highlighting": True,
- "code_lens": True,
- },
- "formatting": {"line_length": 79},
- "keymap": {"preset": "default", "overrides": {}},
- # 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",
- "reactive_tests": True,
- "on_cell_change": "autorun",
- "watcher_on_save": "lazy",
- "output_max_bytes": int(
- os.getenv("MARIMO_OUTPUT_MAX_BYTES", "8000000")
- ),
- "std_stream_max_bytes": int(
- os.getenv("MARIMO_STD_STREAM_MAX_BYTES", "1000000")
- ),
- "default_sql_output": "auto",
- "default_csv_encoding": "utf-8",
- "show_tracebacks": False,
- },
- "save": {
- "autosave": "after_delay",
- "autosave_delay": 1000,
- "format_on_save": False,
- },
- "package_management": {"manager": infer_package_manager()},
- "server": {
- "browser": "default",
- "follow_symlink": False,
- },
- "language_servers": {
- "pylsp": {
- "enabled": False,
- "enable_mypy": True,
- "enable_ruff": True,
- "enable_flake8": False,
- "enable_pydocstyle": False,
- "enable_pylint": False,
- "enable_pyflakes": False,
- }
- },
- "ai": {
- "enabled": True,
- "allow_provider_config": True,
- "models": {
- "displayed_models": [],
- "custom_models": [],
- },
- "custom_providers": {},
- },
- "snippets": {
- "custom_paths": [],
- "include_default_snippets": True,
- },
- "mcp": {
- "mcpServers": {},
- "presets": [],
- },
- "diagnostics": {
- "sql_linter": True,
- },
-}
+DEFAULT_CONFIG: MarimoConfig = cast(
+ MarimoConfig, MarimoConfigSchema().to_dict()
+)
def merge_default_config(
diff --git a/marimo/_config/config_schema.py b/marimo/_config/config_schema.py
new file mode 100644
index 0000000000..afd5d20a38
--- /dev/null
+++ b/marimo/_config/config_schema.py
@@ -0,0 +1,1008 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Struct schema for configuration defaults and field metadata.
+
+The dictionary interfaces in `config.py` remain in use during migration.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Annotated, Any, Literal
+
+from msgspec import UNSET, Meta, UnsetType, field
+
+from marimo._config.packages import infer_package_manager
+from marimo._config.schema_utils import Config
+from marimo._config.types import (
+ CacheVerification,
+ CopilotMode,
+ ExecutionType,
+ ExportType,
+ OnCellChangeType,
+ SqlOutputType,
+ StoreKey,
+ Theme,
+ WidthType,
+)
+
+
+class CompletionConfig(Config, kw_only=True):
+ """Configuration for code completion.
+
+ Settings for code completion in the marimo editor."""
+
+ activate_on_typing: Annotated[
+ bool,
+ Meta(
+ description="if `False`, completion won't activate until the completion hotkey is entered"
+ ),
+ ] = True
+ signature_hint_on_typing: Annotated[
+ bool,
+ Meta(
+ description="if `False`, signature hint won't be shown when typing"
+ ),
+ ] = False
+ copilot: Annotated[
+ bool | Literal["github", "codeium", "custom"],
+ Meta(description='one of `"github"`, `"codeium"`, or `"custom"`'),
+ ] = False
+ auto_close_pairs: Annotated[
+ bool,
+ Meta(
+ description="if `False`, typing an opening bracket, parenthesis, or quote will not automatically insert the closing character"
+ ),
+ ] = True
+ codeium_api_key: Annotated[
+ str | UnsetType | None,
+ Meta(description="the Codeium API key", extra={"sensitive": True}),
+ ] = UNSET
+ api_key: Annotated[
+ str | UnsetType | None,
+ Meta(
+ description="Deprecated completion API key. Use an AI provider configuration instead.",
+ extra={"sensitive": True, "deprecated": True},
+ extra_json_schema={"deprecated": True},
+ ),
+ ] = UNSET
+ model: Annotated[
+ str | UnsetType | None,
+ Meta(
+ description="Deprecated completion model. Use ai.models.autocomplete_model instead.",
+ extra={"deprecated": True},
+ extra_json_schema={"deprecated": True},
+ ),
+ ] = UNSET
+ base_url: Annotated[
+ str | UnsetType | None,
+ Meta(
+ description="Deprecated completion API endpoint. Use an AI provider configuration instead.",
+ extra={"deprecated": True},
+ extra_json_schema={"deprecated": True},
+ ),
+ ] = UNSET
+
+
+class SaveConfig(Config, kw_only=True):
+ """Configuration for saving."""
+
+ autosave: Annotated[
+ Literal["off", "after_delay"],
+ Meta(description='one of `"off"` or `"after_delay"`'),
+ ] = "after_delay"
+ autosave_delay: Annotated[
+ int,
+ Meta(description="Delay in milliseconds before automatically saving."),
+ ] = 1000
+ format_on_save: Annotated[
+ bool, Meta(description="if `True`, format the code on save")
+ ] = False
+
+
+class KeymapConfig(Config, kw_only=True):
+ """Configuration for keymaps."""
+
+ preset: Annotated[
+ Literal["default", "vim"],
+ Meta(description='one of `"default"` or `"vim"`'),
+ ] = "default"
+ overrides: Annotated[
+ dict[str, str],
+ Meta(description="a dict of keymap actions to their keymap override"),
+ ] = field(default_factory=dict)
+ vimrc: Annotated[
+ str | UnsetType | None,
+ Meta(description="path to a vimrc file to load keymaps from"),
+ ] = UNSET
+ destructive_delete: Annotated[
+ bool | UnsetType,
+ Meta(description="if `True`, allows deleting cells with content."),
+ ] = UNSET
+
+
+class VenvConfig(Config, kw_only=True):
+ """Configuration for an external Python environment in edit mode.
+
+ Launches the notebook kernel in an existing virtualenv. Applies to
+ single notebooks and directories when editing without `--sandbox`."""
+
+ path: Annotated[
+ str | UnsetType,
+ Meta(
+ description="path to a virtualenv directory (absolute or relative to pyproject.toml)"
+ ),
+ ] = UNSET
+ writable: Annotated[
+ bool | UnsetType,
+ Meta(
+ description="if true, marimo will manage script metadata (inline dependencies). Defaults to false."
+ ),
+ ] = UNSET
+
+
+class RuntimeConfig(Config, kw_only=True):
+ """Configuration for runtime."""
+
+ auto_instantiate: Annotated[
+ bool,
+ Meta(
+ description="if `False`, cells won't automatically run on startup. This only applies when editing a notebook, and not when running as an application."
+ ),
+ ] = False
+ auto_reload: Annotated[
+ Literal["off", "lazy", "autorun"],
+ Meta(
+ description="If `lazy`, mark cells importing modified modules as stale; if `autorun`, automatically run affected cells. Similar to IPython's %autoreload extension, with dependency-aware execution."
+ ),
+ ] = "off"
+ reactive_tests: Annotated[
+ bool,
+ Meta(
+ description="If `True`, automatically run pytest on cells containing only test functions and test classes."
+ ),
+ ] = True
+ on_cell_change: Annotated[
+ OnCellChangeType,
+ Meta(
+ description="if `lazy`, cells will be marked stale when their ancestors run but won't autorun; if `autorun`, cells will automatically run when their ancestors run."
+ ),
+ ] = "autorun"
+ watcher_on_save: Annotated[
+ Literal["lazy", "autorun"],
+ Meta(
+ description='how to handle file changes when saving. `"lazy"` marks affected cells as stale, `"autorun"` automatically runs affected cells.'
+ ),
+ ] = "lazy"
+ output_max_bytes: Annotated[
+ int,
+ Meta(
+ description="the maximum size in bytes of cell outputs; larger values may affect frontend performance"
+ ),
+ ] = field(
+ default_factory=lambda: int(
+ os.getenv("MARIMO_OUTPUT_MAX_BYTES", "8000000")
+ )
+ )
+ serve_cached_sessions_in_apps: Annotated[
+ bool | UnsetType,
+ Meta(
+ description="if `True`, initialize applications with session cache."
+ ),
+ ] = UNSET
+ std_stream_max_bytes: Annotated[
+ int,
+ Meta(
+ description="the maximum size in bytes of console outputs; larger values may affect frontend performance"
+ ),
+ ] = field(
+ default_factory=lambda: int(
+ os.getenv("MARIMO_STD_STREAM_MAX_BYTES", "1000000")
+ )
+ )
+ pythonpath: Annotated[
+ list[str] | UnsetType,
+ Meta(
+ description="a list of directories to add to the Python search path. Directories will be added to the head of sys.path. Similar to the `PYTHONPATH` environment variable, the directories will be included in where Python will look for imported modules."
+ ),
+ ] = UNSET
+ dotenv: Annotated[
+ list[str] | UnsetType,
+ Meta(
+ description="a list of paths to `.env` files to load. 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.",
+ extra={"sensitive": True},
+ ),
+ ] = UNSET
+ default_sql_output: Annotated[
+ SqlOutputType,
+ Meta(
+ description='the default output format for SQL queries. Can be one of: `"auto"`, `"native"`, `"polars"`, `"lazy-polars"`, or `"pandas"`.'
+ ),
+ ] = "auto"
+ default_auto_download: Annotated[
+ list[ExportType] | UnsetType,
+ Meta(
+ description="an Optional list of export types to automatically snapshot your notebook as: `html`, `markdown`, `ipynb`."
+ ),
+ ] = UNSET
+ default_csv_encoding: Annotated[
+ str, Meta(description="the default encoding for CSV exports.")
+ ] = "utf-8"
+ show_tracebacks: Annotated[
+ bool,
+ Meta(
+ description="if `True`, show detailed error tracebacks in run mode. When enabled, exceptions will display a clickable toast that opens a modal with the full traceback."
+ ),
+ ] = False
+ execution_type: Annotated[
+ ExecutionType | UnsetType,
+ Meta(description="Cell declaration handling: relaxed or strict."),
+ ] = UNSET
+ cache_cells: Annotated[
+ bool | UnsetType,
+ Meta(description="Enable experimental automatic cell caching."),
+ ] = UNSET
+ pin_modules: Annotated[
+ bool | UnsetType,
+ Meta(description="Pin imported modules when caching cells."),
+ ] = UNSET
+
+
+class DisplayConfig(Config, kw_only=True):
+ """Configuration for display."""
+
+ theme: Annotated[
+ Theme, Meta(description='`"light"`, `"dark"`, or `"system"`')
+ ] = "light"
+ code_editor_font_size: Annotated[
+ int, Meta(description="font size for the code editor")
+ ] = 14
+ cell_output: Annotated[
+ Literal["above", "below"], Meta(description='`"above"` or `"below"`')
+ ] = "below"
+ default_width: Annotated[
+ WidthType, Meta(description="Default notebook width.")
+ ] = "medium"
+ dataframes: Annotated[
+ Literal["rich", "plain"], Meta(description='`"rich"` or `"plain"`')
+ ] = "rich"
+ custom_css: Annotated[
+ list[str] | UnsetType,
+ Meta(description="list of paths to custom CSS files"),
+ ] = UNSET
+ default_table_page_size: Annotated[
+ int, Meta(description="default number of rows to display in tables")
+ ] = 10
+ default_table_max_columns: Annotated[
+ int,
+ Meta(
+ description="default maximum number of columns to display in tables"
+ ),
+ ] = 50
+ reference_highlighting: Annotated[
+ bool,
+ Meta(description="if `True`, highlight reactive variable references"),
+ ] = True
+ code_lens: Annotated[
+ bool,
+ Meta(
+ description="if `True`, show inline icons in cell editors linking datasources, storage buckets, and caches to their panels"
+ ),
+ ] = True
+ locale: Annotated[
+ str | UnsetType | None,
+ Meta(
+ description='locale for date formatting and internationalization (e.g., "en-US", "en-GB", "de-DE")'
+ ),
+ ] = UNSET
+
+
+class FormattingConfig(Config, kw_only=True):
+ """Configuration for code formatting."""
+
+ line_length: Annotated[int, Meta(description="max line length")] = 79
+
+
+class ServerConfig(Config, kw_only=True):
+ """Configuration for the server."""
+
+ browser: Annotated[
+ Literal["default"] | str,
+ Meta(
+ description='the web browser to use. `"default"` or a browser registered with Python\'s webbrowser module (eg, `"firefox"` or `"chrome"`)'
+ ),
+ ] = "default"
+ follow_symlink: Annotated[
+ bool,
+ Meta(
+ description="if true, the server will follow symlinks it finds inside its static assets directory."
+ ),
+ ] = False
+ disable_file_downloads: Annotated[
+ bool | UnsetType,
+ Meta(
+ description="if true, the file download button will be hidden in the file explorer."
+ ),
+ ] = UNSET
+ transport: Annotated[
+ Literal["websocket", "sse"] | UnsetType,
+ Meta(
+ description='experimental. The transport used to stream kernel messages to the frontend, typically set with the `MARIMO_SERVER_TRANSPORT` environment variable. `"websocket"` (default) uses the `/ws` WebSocket endpoint; `"sse"` uses server-sent events over HTTP, for deployments behind proxies or services that do not support WebSockets. Terminal, LSP, and real-time collaboration still require WebSockets; RTC is disabled when using `"sse"`.'
+ ),
+ ] = UNSET
+
+
+class PackageManagementConfig(Config, kw_only=True):
+ """Configuration options for package management."""
+
+ manager: Annotated[
+ Literal["pip", "rye", "uv", "poetry", "pixi"],
+ Meta(description="the package manager to use"),
+ ] = field(default_factory=infer_package_manager)
+
+
+class AiModelConfig(Config, kw_only=True):
+ """Configuration options for an AI model."""
+
+ chat_model: Annotated[
+ str | UnsetType | None,
+ Meta(description="the model to use for chat completions"),
+ ] = UNSET
+ edit_model: Annotated[
+ str | UnsetType | None,
+ Meta(description="the model to use for edit completions"),
+ ] = UNSET
+ autocomplete_model: Annotated[
+ str | UnsetType | None,
+ Meta(description="the model to use for code completion/autocomplete"),
+ ] = UNSET
+ displayed_models: Annotated[
+ list[str], Meta(description="a list of models to display in the UI")
+ ] = field(default_factory=list)
+ custom_models: Annotated[
+ list[str],
+ Meta(
+ description="a list of custom models to use that are not from the default list"
+ ),
+ ] = field(default_factory=list)
+
+
+class AiConfig(Config, kw_only=True):
+ """Configuration options for AI."""
+
+ enabled: Annotated[
+ bool,
+ Meta(
+ description="if `False`, hide AI actions and panels in the marimo UI"
+ ),
+ ] = True
+ rules: Annotated[
+ str | UnsetType,
+ Meta(
+ description="custom rules to include in all AI completion prompts"
+ ),
+ ] = UNSET
+ max_tokens: Annotated[
+ int | UnsetType | None,
+ Meta(
+ description="the maximum number of tokens to use in AI completions"
+ ),
+ ] = UNSET
+ mode: Annotated[
+ CopilotMode | UnsetType,
+ Meta(
+ description='the mode to use for AI completions. Can be one of: `"ask"` or `"manual"`'
+ ),
+ ] = UNSET
+ inline_tooltip: Annotated[
+ bool | UnsetType,
+ Meta(description="if `True`, enable inline AI tooltip suggestions"),
+ ] = UNSET
+ allow_provider_config: Annotated[
+ bool,
+ Meta(
+ description="if `False`, lock provider setup in the settings UI, making them read-only. Users cannot bring their own credentials or add custom providers. Default `True`."
+ ),
+ ] = True
+ models: Annotated[
+ AiModelConfig, Meta(description="the models to use for AI completions")
+ ] = field(default_factory=AiModelConfig)
+ open_ai: Annotated[
+ OpenAiConfig | UnsetType, Meta(description="the OpenAI config")
+ ] = UNSET
+ anthropic: Annotated[
+ AnthropicConfig | UnsetType, Meta(description="the Anthropic config")
+ ] = UNSET
+ google: Annotated[
+ GoogleAiConfig | UnsetType, Meta(description="the Google AI config")
+ ] = UNSET
+ bedrock: Annotated[
+ BedrockConfig | UnsetType, Meta(description="the Bedrock config")
+ ] = UNSET
+ azure: Annotated[
+ OpenAiConfig | UnsetType, Meta(description="the Azure config")
+ ] = UNSET
+ ollama: Annotated[
+ OpenAiConfig | UnsetType, Meta(description="the Ollama config")
+ ] = UNSET
+ github: Annotated[
+ GitHubConfig | UnsetType, Meta(description="the GitHub Copilot config")
+ ] = UNSET
+ openrouter: Annotated[
+ OpenAiConfig | UnsetType, Meta(description="the OpenRouter config")
+ ] = UNSET
+ wandb: Annotated[
+ OpenAiConfig | UnsetType,
+ Meta(description="the Weights & Biases config"),
+ ] = UNSET
+ opencode_go: Annotated[
+ OpenAiConfig | UnsetType, Meta(description="the OpenCode Go config")
+ ] = UNSET
+ custom_providers: Annotated[
+ dict[str, OpenAiConfig],
+ Meta(description="a dict of custom OpenAI-compatible providers"),
+ ] = field(default_factory=dict)
+ open_ai_compatible: Annotated[
+ OpenAiConfig | UnsetType,
+ Meta(
+ description="the OpenAI-compatible config (deprecated, use custom_providers)",
+ extra={"deprecated": True},
+ extra_json_schema={"deprecated": True},
+ ),
+ ] = UNSET
+
+
+class OpenAiConfig(Config, kw_only=True):
+ """Configuration options for OpenAI or OpenAI-compatible services."""
+
+ api_key: Annotated[
+ str | UnsetType,
+ Meta(
+ description="the OpenAI API key or an `env:` reference",
+ extra={"sensitive": True},
+ ),
+ ] = UNSET
+ base_url: Annotated[
+ str | UnsetType, Meta(description="the base URL for the API")
+ ] = UNSET
+ project: Annotated[
+ str | UnsetType, Meta(description="the project ID for the OpenAI API")
+ ] = UNSET
+ ssl_verify: Annotated[
+ bool | UnsetType,
+ Meta(
+ description="Whether to verify TLS certificates for the API client."
+ ),
+ ] = UNSET
+ ca_bundle_path: Annotated[
+ str | UnsetType,
+ Meta(
+ description="custom ca bundle to be used for verifying SSL certificates. Used to create custom SSL context for httpx client"
+ ),
+ ] = UNSET
+ client_pem: Annotated[
+ str | UnsetType,
+ Meta(
+ description="Path to a client PEM certificate for authenticating API requests."
+ ),
+ ] = UNSET
+ extra_headers: Annotated[
+ dict[str, str] | UnsetType,
+ Meta(
+ description="extra headers to be passed to the OpenAI client",
+ extra={"sensitive": True},
+ ),
+ ] = UNSET
+ model: Annotated[
+ str | UnsetType,
+ Meta(
+ description="Deprecated chat model. Use ai.models.chat_model instead.",
+ extra={"deprecated": True},
+ extra_json_schema={"deprecated": True},
+ ),
+ ] = UNSET
+
+
+class AnthropicConfig(Config, kw_only=True):
+ """Configuration options for Anthropic."""
+
+ api_key: Annotated[
+ str | UnsetType,
+ Meta(
+ description="the Anthropic API key or an `env:` reference",
+ extra={"sensitive": True},
+ ),
+ ] = UNSET
+
+
+class GoogleAiConfig(Config, kw_only=True):
+ """Configuration options for Google AI."""
+
+ api_key: Annotated[
+ str | UnsetType,
+ Meta(
+ description="the Google AI API key or an `env:` reference",
+ extra={"sensitive": True},
+ ),
+ ] = UNSET
+
+
+class BedrockConfig(Config, kw_only=True):
+ """Configuration options for Bedrock."""
+
+ profile_name: Annotated[
+ str | UnsetType, Meta(description="the AWS profile to use")
+ ] = UNSET
+ region_name: Annotated[
+ str | UnsetType, Meta(description="the AWS region to use")
+ ] = UNSET
+ aws_access_key_id: Annotated[
+ str | UnsetType,
+ Meta(description="the AWS access key ID", extra={"sensitive": True}),
+ ] = UNSET
+ aws_secret_access_key: Annotated[
+ str | UnsetType,
+ Meta(
+ description="the AWS secret access key", extra={"sensitive": True}
+ ),
+ ] = UNSET
+
+
+class GitHubConfig(Config, kw_only=True):
+ """Configuration options for GitHub Copilot."""
+
+ api_key: Annotated[
+ str | UnsetType,
+ Meta(
+ description="a GitHub Copilot token or an `env:` reference",
+ extra={"sensitive": True},
+ ),
+ ] = UNSET
+ base_url: Annotated[
+ str | UnsetType,
+ Meta(description="the base URL for the GitHub Copilot API"),
+ ] = UNSET
+ copilot_settings: Annotated[
+ dict[str, Any] | UnsetType,
+ Meta(
+ description="configuration settings for GitHub Copilot LSP. Supports settings like `http` (proxy configuration), `telemetry`, and `github-enterprise` (enterprise URI)."
+ ),
+ ] = UNSET
+
+
+class PythonLanguageServerConfig(Config, kw_only=True):
+ """Configuration options for Python Language Server.
+
+ pylsp handles completion, hover, go-to-definition, and diagnostics."""
+
+ enabled: Annotated[
+ bool, Meta(description="Enable this language server.")
+ ] = False
+ enable_mypy: Annotated[
+ bool, Meta(description="Enable mypy diagnostics in pylsp.")
+ ] = True
+ enable_ruff: Annotated[
+ bool, Meta(description="Enable ruff diagnostics in pylsp.")
+ ] = True
+ enable_flake8: Annotated[
+ bool, Meta(description="Enable flake8 diagnostics in pylsp.")
+ ] = False
+ enable_pydocstyle: Annotated[
+ bool, Meta(description="Enable pydocstyle diagnostics in pylsp.")
+ ] = False
+ enable_pylint: Annotated[
+ bool, Meta(description="Enable pylint diagnostics in pylsp.")
+ ] = False
+ enable_pyflakes: Annotated[
+ bool, Meta(description="Enable pyflakes diagnostics in pylsp.")
+ ] = False
+
+
+class BasedpyrightServerConfig(Config, kw_only=True):
+ """Configuration options for basedpyright Language Server.
+
+ basedpyright handles completion, hover, go-to-definition, and diagnostics,
+ but we only use it for diagnostics."""
+
+ enabled: Annotated[
+ bool | UnsetType, Meta(description="Enable this language server.")
+ ] = UNSET
+
+
+class TyLanguageServerConfig(Config, kw_only=True):
+ """Configuration options for Ty Language Server.
+
+ ty handles completion, hover, go-to-definition, and diagnostics,
+ but we only use it for diagnostics."""
+
+ enabled: Annotated[
+ bool | UnsetType, Meta(description="Enable this language server.")
+ ] = UNSET
+
+
+class PyreflyLanguageServerConfig(Config, kw_only=True):
+ """Configuration options for Pyrefly Language Server.
+
+ Pyrefly handles completion, hover, go-to-definition, and diagnostics."""
+
+ enabled: Annotated[
+ bool | UnsetType, Meta(description="Enable this language server.")
+ ] = UNSET
+
+
+class LanguageServersConfig(Config, kw_only=True):
+ """Configuration options for language servers."""
+
+ pylsp: Annotated[
+ PythonLanguageServerConfig, Meta(description="the pylsp config")
+ ] = field(default_factory=PythonLanguageServerConfig)
+ basedpyright: Annotated[
+ BasedpyrightServerConfig | UnsetType,
+ Meta(description="the basedpyright config"),
+ ] = UNSET
+ ty: Annotated[
+ TyLanguageServerConfig | UnsetType, Meta(description="the ty config")
+ ] = UNSET
+ pyrefly: Annotated[
+ PyreflyLanguageServerConfig | UnsetType,
+ Meta(description="the pyrefly config"),
+ ] = UNSET
+
+
+class DiagnosticsConfig(Config, kw_only=True):
+ """Configuration options for diagnostics."""
+
+ enabled: Annotated[
+ bool | UnsetType,
+ Meta(description="if `True`, diagnostics will be shown in the editor"),
+ ] = UNSET
+ sql_linter: Annotated[
+ bool,
+ Meta(description="if `True`, SQL cells will have linting enabled"),
+ ] = True
+
+
+class LintConfig(Config, kw_only=True):
+ """Configuration for lint rule selection.
+
+ Follows ruff-inspired semantics for selecting which rules to run
+ during `marimo check`."""
+
+ select: Annotated[
+ list[str] | UnsetType,
+ Meta(
+ description='list of rule code prefixes that replaces the default enabled set. Use `"ALL"` to select all rules. Example: `["MB", "MR001"]`'
+ ),
+ ] = UNSET
+ ignore: Annotated[
+ list[str] | UnsetType,
+ Meta(
+ description="list of rule code prefixes to remove from the enabled set."
+ ),
+ ] = UNSET
+
+
+class SnippetsConfig(Config, kw_only=True):
+ """Configuration for snippets."""
+
+ custom_paths: Annotated[
+ list[str],
+ Meta(description="Paths to directories containing custom snippets."),
+ ] = field(default_factory=list)
+ include_default_snippets: Annotated[
+ bool, Meta(description="Include the built-in snippets.")
+ ] = True
+
+
+class DatasourcesConfig(Config, kw_only=True):
+ """Configuration for datasources panel."""
+
+ auto_discover_schemas: Annotated[
+ bool | Literal["auto"] | UnsetType,
+ Meta(description="if `True`, include schemas in the datasource"),
+ ] = UNSET
+ auto_discover_tables: Annotated[
+ bool | Literal["auto"] | UnsetType,
+ Meta(description="if `True`, include tables in the datasource"),
+ ] = UNSET
+ auto_discover_columns: Annotated[
+ bool | Literal["auto"] | UnsetType,
+ Meta(
+ description="if `True`, include columns & table metadata in the datasource"
+ ),
+ ] = UNSET
+
+
+class FolderConfig(Config, kw_only=True):
+ """Configuration for an additional file browser root."""
+
+ path: Annotated[str, Meta(description="the absolute path to the folder")]
+ name: Annotated[
+ str | UnsetType,
+ Meta(description="an optional display name for the folder"),
+ ] = UNSET
+
+
+class FileBrowserConfig(Config, kw_only=True):
+ """Configuration for the file browser panel."""
+
+ folders: Annotated[
+ list[FolderConfig] | UnsetType,
+ Meta(
+ description="additional absolute folders to show in the file browser"
+ ),
+ ] = UNSET
+
+
+class SharingConfig(Config, kw_only=True):
+ """Configuration for sharing features."""
+
+ html: Annotated[
+ bool | UnsetType,
+ Meta(
+ description="if `False`, HTML sharing options will be hidden from the UI"
+ ),
+ ] = UNSET
+ wasm: Annotated[
+ bool | UnsetType,
+ Meta(
+ description="if `False`, WebAssembly sharing options will be hidden from the UI"
+ ),
+ ] = UNSET
+ molab: Annotated[
+ bool | UnsetType,
+ Meta(
+ description="if `False`, molab sharing options will be hidden from the UI"
+ ),
+ ] = UNSET
+
+
+class StoreConfig(Config, kw_only=True):
+ """Configuration for a single cache store."""
+
+ type: Annotated[
+ StoreKey | UnsetType, Meta(description="Cache store backend.")
+ ] = UNSET
+ args: Annotated[
+ dict[str, Any] | UnsetType,
+ Meta(
+ description="Keyword arguments passed to the cache store constructor."
+ ),
+ ] = UNSET
+
+
+CacheStoreConfig = list[StoreConfig] | StoreConfig
+
+
+class CacheConfig(Config, kw_only=True):
+ """Configuration for caching."""
+
+ verification: Annotated[
+ CacheVerification | UnsetType,
+ Meta(
+ description="Cache signature verification posture: off, on, or strict."
+ ),
+ ] = UNSET
+ store: Annotated[
+ CacheStoreConfig | UnsetType,
+ Meta(
+ description="Backing cache store, or a list of stores composed into a tiered store."
+ ),
+ ] = UNSET
+
+
+class SigningConfig(Config, kw_only=True):
+ """Cache-signing trust and identity."""
+
+ trusted_signers: Annotated[
+ dict[str, str] | UnsetType,
+ Meta(
+ description="Trusted key fingerprints (SHA256:<base64>) mapped to advisory labels. Trust permits code execution when restoring cached Python objects."
+ ),
+ ] = UNSET
+ private_key_path: Annotated[
+ str | UnsetType,
+ Meta(
+ description="Absolute path to this machine's private signing key. Not exposed to the frontend.",
+ extra={"sensitive": True},
+ ),
+ ] = UNSET
+
+
+class ExperimentalConfig(Config, kw_only=True):
+ """Configuration for experimental features.
+
+ Features exposed on the frontend must match the frontend config."""
+
+ markdown: Annotated[
+ bool | UnsetType,
+ Meta(description="Enable experimental Markdown notebook features."),
+ ] = UNSET
+ wasm_layouts: Annotated[
+ bool | UnsetType,
+ Meta(
+ description="Enable experimental layouts in WebAssembly notebooks."
+ ),
+ ] = UNSET
+ rtc_v2: Annotated[
+ bool | UnsetType, Meta(description="Enable real-time collaboration.")
+ ] = UNSET
+ isolate_apps: Annotated[
+ bool | UnsetType,
+ Meta(description="Run applications in separate processes."),
+ ] = UNSET
+ debugger: Annotated[
+ bool | UnsetType,
+ Meta(
+ description="Enable live debugging with gutter breakpoints and pdb."
+ ),
+ ] = UNSET
+ line_timing: Annotated[
+ bool | UnsetType,
+ Meta(
+ description="Highlight the active line and show per-line execution timing."
+ ),
+ ] = UNSET
+ execution_type: Annotated[
+ ExecutionType | UnsetType,
+ Meta(
+ description="Experimental cell declaration handling: relaxed or strict."
+ ),
+ ] = UNSET
+
+
+class MCPServerStdioConfig(
+ Config, kw_only=True, tag="stdio", tag_field="__marimo_transport__"
+):
+ """Configuration for STDIO transport MCP servers"""
+
+ command: Annotated[
+ str, Meta(description="Command used to launch the MCP server.")
+ ]
+ args: Annotated[
+ list[str] | UnsetType | None,
+ Meta(description="Arguments passed to the MCP server command."),
+ ] = UNSET
+ env: Annotated[
+ dict[str, str] | UnsetType | None,
+ Meta(
+ description="Environment variables supplied to the MCP server.",
+ extra={"sensitive": True},
+ ),
+ ] = UNSET
+ disabled: Annotated[
+ bool | UnsetType | None, Meta(description="Disable this MCP server.")
+ ] = UNSET
+
+
+class MCPServerStreamableHttpConfig(
+ Config, kw_only=True, tag="http", tag_field="__marimo_transport__"
+):
+ """Configuration for Streamable HTTP transport MCP servers"""
+
+ url: Annotated[
+ str, Meta(description="URL of the streamable HTTP MCP server.")
+ ]
+ headers: Annotated[
+ dict[str, str] | UnsetType | None,
+ Meta(
+ description="HTTP headers sent to the MCP server.",
+ extra={"sensitive": True},
+ ),
+ ] = UNSET
+ timeout: Annotated[
+ float | UnsetType | None,
+ Meta(description="Timeout in seconds for MCP server requests."),
+ ] = UNSET
+ env: Annotated[
+ dict[str, str] | UnsetType | None,
+ Meta(
+ description="Environment variables used by the MCP server configuration.",
+ extra={"sensitive": True},
+ ),
+ ] = UNSET
+ disabled: Annotated[
+ bool | UnsetType | None, Meta(description="Disable this MCP server.")
+ ] = UNSET
+
+
+MCPServerConfig = MCPServerStdioConfig | MCPServerStreamableHttpConfig
+
+
+class MCPConfig(Config, kw_only=True):
+ """Configuration for MCP servers
+
+ Note: the field name `mcpServers` is camelCased to match MCP server
+ config conventions used by popular AI applications (e.g. Cursor, Claude Desktop, etc.)"""
+
+ mcpServers: Annotated[
+ dict[str, MCPServerConfig],
+ Meta(description="Named MCP server configurations."),
+ ] = field(default_factory=dict)
+ presets: Annotated[
+ list[Literal["marimo", "context7"]],
+ Meta(description="Built-in MCP server presets to enable."),
+ ] = field(default_factory=list)
+ _mcp_path = ()
+
+
+class MarimoConfig(Config, kw_only=True):
+ """Configuration for the marimo editor"""
+
+ completion: Annotated[
+ CompletionConfig,
+ Meta(description="Configuration for code completion."),
+ ] = field(default_factory=CompletionConfig)
+ display: Annotated[
+ DisplayConfig, Meta(description="Configuration for display.")
+ ] = field(default_factory=DisplayConfig)
+ formatting: Annotated[
+ FormattingConfig,
+ Meta(description="Configuration for code formatting."),
+ ] = field(default_factory=FormattingConfig)
+ keymap: Annotated[
+ KeymapConfig, Meta(description="Configuration for keymaps.")
+ ] = field(default_factory=KeymapConfig)
+ runtime: Annotated[
+ RuntimeConfig, Meta(description="Configuration for runtime.")
+ ] = field(default_factory=RuntimeConfig)
+ save: Annotated[
+ SaveConfig, Meta(description="Configuration for saving.")
+ ] = field(default_factory=SaveConfig)
+ server: Annotated[
+ ServerConfig, Meta(description="Configuration for the server.")
+ ] = field(default_factory=ServerConfig)
+ package_management: Annotated[
+ PackageManagementConfig,
+ Meta(description="Configuration options for package management."),
+ ] = field(default_factory=PackageManagementConfig)
+ ai: Annotated[
+ AiConfig, Meta(description="Configuration options for AI.")
+ ] = field(default_factory=AiConfig)
+ language_servers: Annotated[
+ LanguageServersConfig,
+ Meta(description="Configuration options for language servers."),
+ ] = field(default_factory=LanguageServersConfig)
+ diagnostics: Annotated[
+ DiagnosticsConfig,
+ Meta(description="Configuration options for diagnostics."),
+ ] = field(default_factory=DiagnosticsConfig)
+ lint: Annotated[
+ LintConfig | UnsetType,
+ Meta(description="Configuration for lint rule selection."),
+ ] = UNSET
+ experimental: Annotated[
+ ExperimentalConfig | UnsetType,
+ Meta(description="Configuration for experimental features."),
+ ] = UNSET
+ snippets: Annotated[
+ SnippetsConfig, Meta(description="Configuration for snippets.")
+ ] = field(default_factory=SnippetsConfig)
+ datasources: Annotated[
+ DatasourcesConfig | UnsetType,
+ Meta(description="Configuration for datasources panel."),
+ ] = UNSET
+ file_browser: Annotated[
+ FileBrowserConfig | UnsetType,
+ Meta(description="Configuration for the file browser panel."),
+ ] = UNSET
+ sharing: Annotated[
+ SharingConfig | UnsetType,
+ Meta(description="Configuration for sharing features."),
+ ] = UNSET
+ mcp: Annotated[
+ MCPConfig, Meta(description="Configuration for MCP servers")
+ ] = field(default_factory=MCPConfig)
+ venv: Annotated[
+ VenvConfig | UnsetType,
+ Meta(
+ description="Configuration for an external Python environment in edit mode."
+ ),
+ ] = UNSET
+ cache: Annotated[
+ CacheConfig | UnsetType, Meta(description="Configuration for caching.")
+ ] = UNSET
+ signing: Annotated[
+ SigningConfig | UnsetType,
+ Meta(description="Cache-signing trust and identity."),
+ ] = UNSET
+ _mcp_path = ("mcp",)
diff --git a/marimo/_config/schema_utils.py b/marimo/_config/schema_utils.py
new file mode 100644
index 0000000000..a7b21aa130
--- /dev/null
+++ b/marimo/_config/schema_utils.py
@@ -0,0 +1,151 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Compatibility helpers for typed user configuration."""
+
+from __future__ import annotations
+
+import copy
+import sys
+from typing import (
+ Annotated,
+ Any,
+ ClassVar,
+ get_args,
+ get_origin,
+ get_type_hints,
+)
+
+import msgspec
+from msgspec import UNSET, Meta
+from msgspec.structs import fields
+
+if sys.version_info >= (3, 11):
+ from typing import Self
+else:
+ from typing_extensions import Self
+
+
+def default_if_unset(value: Any, default: Any) -> Any:
+ """Use a fallback only for absent values, preserving explicit None."""
+ return default if value is UNSET else value
+
+
+def _prepare_mcp_config(
+ values: dict[str, object], path: tuple[str, ...] | None
+) -> dict[str, object]:
+ """Infer internal union tags without changing the user's MCP format."""
+ prepared = copy.deepcopy(values)
+ section: Any = prepared
+ for key in path or ():
+ if not isinstance(section, dict) or key not in section:
+ return prepared
+ section = section[key]
+ if path is not None and isinstance(section, dict):
+ servers = section.get("mcpServers")
+ if isinstance(servers, dict):
+ for server in servers.values():
+ if isinstance(server, dict):
+ # Keep the legacy command-first selection for ambiguous inputs.
+ if "command" in server:
+ server["__marimo_transport__"] = "stdio"
+ elif "url" in server:
+ server["__marimo_transport__"] = "http"
+ return prepared
+
+
+def _retain_unknown_fields(value: object, source: object) -> None:
+ """Keep unknown settings at every level for lossless load/save cycles."""
+ if isinstance(value, Config) and isinstance(source, dict):
+ names = {item.encode_name for item in fields(value)}
+ value._extra_fields = copy.deepcopy(
+ {key: item for key, item in source.items() if key not in names}
+ )
+ for item in fields(value):
+ if item.encode_name in source:
+ _retain_unknown_fields(
+ getattr(value, item.name), source[item.encode_name]
+ )
+ elif isinstance(value, dict) and isinstance(source, dict):
+ for key, item in value.items():
+ if key in source:
+ _retain_unknown_fields(item, source[key])
+ elif isinstance(value, list) and isinstance(source, list):
+ for item, original in zip(value, source, strict=True):
+ _retain_unknown_fields(item, original)
+
+
+def _restore_unknown_fields(value: object, serialized: Any) -> Any:
+ """Restore retained settings and remove internal MCP discriminators."""
+ if isinstance(value, Config):
+ tag_field = value.__struct_config__.tag_field
+ if value.__struct_config__.tag is not None:
+ serialized.pop(tag_field, None)
+ for item in fields(value):
+ if item.encode_name in serialized:
+ serialized[item.encode_name] = _restore_unknown_fields(
+ getattr(value, item.name), serialized[item.encode_name]
+ )
+ return {
+ **copy.deepcopy(value._extra_fields),
+ **serialized,
+ }
+ if isinstance(value, dict):
+ return {
+ key: _restore_unknown_fields(item, serialized[key])
+ for key, item in value.items()
+ if key in serialized
+ }
+ if isinstance(value, list):
+ return [
+ _restore_unknown_fields(item, encoded)
+ for item, encoded in zip(value, serialized, strict=True)
+ ]
+ return serialized
+
+
+class Config(msgspec.Struct, dict=True, kw_only=True):
+ """Base for user settings with presence tracking and unknown-key retention."""
+
+ _mcp_path: ClassVar[tuple[str, ...] | None] = None
+
+ def __post_init__(self) -> None:
+ self._extra_fields: dict[str, object] = {}
+
+ def __rich_repr__(self) -> list[tuple[str, Any]]:
+ metadata = {
+ name: metadata
+ for name, annotation in get_type_hints(
+ type(self), include_extras=True
+ ).items()
+ if get_origin(annotation) is Annotated
+ for metadata in get_args(annotation)[1:]
+ if isinstance(metadata, Meta)
+ }
+ return [
+ (item.name, getattr(self, item.name))
+ for item in fields(self)
+ if not (metadata.get(item.name, Meta()).extra or {}).get(
+ "sensitive"
+ )
+ ]
+
+ def __repr__(self) -> str:
+ values = ", ".join(
+ f"{name}={value!r}" for name, value in self.__rich_repr__()
+ )
+ return f"{type(self).__name__}({values})"
+
+ @classmethod
+ def from_dict(cls, values: dict[str, object]) -> Self:
+ """Validate settings, retaining unknown keys and legacy MCP inputs."""
+ config = msgspec.convert(
+ _prepare_mcp_config(values, cls._mcp_path), type=cls
+ )
+ _retain_unknown_fields(config, values)
+ return config
+
+ def to_dict(self) -> dict[str, Any]:
+ """Serialize settings without unset fields or internal MCP tags."""
+ serialized: dict[str, Any] = _restore_unknown_fields(
+ self, msgspec.to_builtins(self)
+ )
+ return serialized
diff --git a/marimo/_config/types.py b/marimo/_config/types.py
new file mode 100644
index 0000000000..1745bb5dfd
--- /dev/null
+++ b/marimo/_config/types.py
@@ -0,0 +1,16 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+from typing import Literal
+
+OnCellChangeType = Literal["lazy", "autorun"]
+ExecutionType = Literal["relaxed", "strict"]
+# TODO(akshayka): remove normal, migrate to compact
+# normal == compact
+WidthType = Literal["normal", "compact", "medium", "full", "columns"]
+Theme = Literal["light", "dark", "system"]
+ExportType = Literal["html", "markdown", "ipynb"]
+SqlOutputType = Literal["polars", "lazy-polars", "pandas", "native", "auto"]
+StoreKey = Literal["file", "redis", "rest", "tiered"]
+CopilotMode = Literal["ask", "manual", "agent", "code_mode"]
+CacheVerification = Literal["off", "on", "strict"]
diff --git a/tests/_config/test_config_schema.py b/tests/_config/test_config_schema.py
new file mode 100644
index 0000000000..b63a11e84f
--- /dev/null
+++ b/tests/_config/test_config_schema.py
@@ -0,0 +1,401 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import sys
+import types
+from typing import (
+ TYPE_CHECKING,
+ Any,
+ Union,
+ get_args,
+ get_origin,
+ get_type_hints,
+)
+
+import msgspec
+import pytest
+from msgspec import UNSET, UnsetType
+
+from marimo._config import config as legacy_config, config_schema
+from marimo._config.config import (
+ DEFAULT_CONFIG,
+ merge_config,
+ merge_default_config,
+)
+from marimo._config.config_schema import MarimoConfig
+from marimo._config.manager import UserConfigStore
+from marimo._config.schema_utils import (
+ Config,
+ default_if_unset,
+)
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+if sys.version_info >= (3, 11):
+ from typing import NotRequired
+else:
+ from typing_extensions import NotRequired
+
+
+SCHEMA_CLASSES = [
+ cls
+ for cls in vars(config_schema).values()
+ if isinstance(cls, type)
+ and issubclass(cls, Config)
+ and cls.__module__ == config_schema.__name__
+]
+
+
+def test_schema_defaults_preserve_dictionary_api() -> None:
+ defaults = MarimoConfig(
+ runtime=config_schema.RuntimeConfig(
+ output_max_bytes=DEFAULT_CONFIG["runtime"]["output_max_bytes"],
+ std_stream_max_bytes=DEFAULT_CONFIG["runtime"][
+ "std_stream_max_bytes"
+ ],
+ ),
+ package_management=config_schema.PackageManagementConfig(
+ manager=DEFAULT_CONFIG["package_management"]["manager"]
+ ),
+ )
+ assert defaults.to_dict() == DEFAULT_CONFIG
+ resolved = merge_default_config({"display": {"theme": "dark"}})
+ assert isinstance(resolved, dict)
+ assert resolved["display"] == {
+ **DEFAULT_CONFIG["display"],
+ "theme": "dark",
+ }
+
+
+def test_runtime_defaults_read_environment(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setenv("MARIMO_OUTPUT_MAX_BYTES", "1234")
+ monkeypatch.setenv("MARIMO_STD_STREAM_MAX_BYTES", "5678")
+ assert config_schema.RuntimeConfig().to_dict() == {
+ **DEFAULT_CONFIG["runtime"],
+ "output_max_bytes": 1234,
+ "std_stream_max_bytes": 5678,
+ }
+
+
[email protected]("cls", SCHEMA_CLASSES, ids=lambda cls: cls.__name__)
+def test_schema_fields_have_descriptions(cls: type[Config]) -> None:
+ assert issubclass(cls, msgspec.Struct)
+ properties = msgspec.json.schema(cls)["$defs"][cls.__name__]["properties"]
+ assert all(
+ properties[name].get("description") for name in cls.__struct_fields__
+ )
+
+
+def _normalize_type(annotation: Any) -> Any:
+ origin = get_origin(annotation)
+ args = get_args(annotation)
+ if origin is NotRequired:
+ return _normalize_type(args[0])
+ if origin in (Union, types.UnionType):
+ present = [
+ _normalize_type(arg) for arg in args if arg is not UnsetType
+ ]
+ return present[0] if len(present) == 1 else frozenset(present)
+ if origin is not None:
+ return (origin, tuple(_normalize_type(arg) for arg in args))
+ if isinstance(annotation, type) and (
+ issubclass(annotation, Config)
+ or hasattr(annotation, "__required_keys__")
+ ):
+ return annotation.__name__
+ return annotation
+
+
[email protected]("cls", SCHEMA_CLASSES, ids=lambda cls: cls.__name__)
+def test_schema_preserves_existing_field_types(cls: type[Config]) -> None:
+ legacy_cls = getattr(legacy_config, cls.__name__)
+ legacy_hints = get_type_hints(
+ legacy_cls,
+ localns={
+ "MCPServerConfig": legacy_config.MCPServerStdioConfig
+ | legacy_config.MCPServerStreamableHttpConfig
+ },
+ include_extras=True,
+ )
+ schema_hints = get_type_hints(cls)
+ for name, annotation in legacy_hints.items():
+ if cls is MarimoConfig and name == "experimental":
+ continue
+ # These scalars can be cleared with null by the settings UI.
+ if (cls is config_schema.AiConfig and name == "max_tokens") or (
+ cls is config_schema.AiModelConfig
+ and name in {"chat_model", "edit_model", "autocomplete_model"}
+ ):
+ annotation = Union[annotation, None]
+ assert _normalize_type(schema_hints[name]) == _normalize_type(
+ annotation
+ )
+
+
+def test_defaults_are_independent() -> None:
+ first = MarimoConfig()
+ second = MarimoConfig()
+ before = second.to_dict()
+ first.ai.models.displayed_models.append("custom-model")
+ first.keymap.overrides["run"] = "Ctrl-Enter"
+ first.mcp.presets.append("marimo")
+
+ assert second.to_dict() == before
+
+
+ ("value", "expected"),
+ [(UNSET, "fallback"), (None, None), (False, False), (0, 0), ("", "")],
+)
+def test_default_if_unset_preserves_explicit_values(
+ value: Any, expected: Any
+) -> None:
+ assert default_if_unset(value, "fallback") == expected
+
+
+def test_nested_conversion_preserves_presence() -> None:
+ config = config_schema.AiConfig.from_dict(
+ {
+ "max_tokens": None,
+ "open_ai": {"api_key": "secret"},
+ "custom_providers": {
+ "gateway": {"base_url": "https://example.com"}
+ },
+ }
+ )
+ assert isinstance(config.open_ai, config_schema.OpenAiConfig)
+ assert isinstance(
+ config.custom_providers["gateway"], config_schema.OpenAiConfig
+ )
+ assert config.to_dict() == {
+ "enabled": True,
+ "allow_provider_config": True,
+ "models": {"displayed_models": [], "custom_models": []},
+ "max_tokens": None,
+ "open_ai": {"api_key": "secret"},
+ "custom_providers": {"gateway": {"base_url": "https://example.com"}},
+ }
+ assert "secret" not in repr(config)
+
+
+def test_list_and_union_conversion() -> None:
+ folders = config_schema.FileBrowserConfig.from_dict(
+ {"folders": [{"path": "/data"}]}
+ )
+ assert folders.folders == [config_schema.FolderConfig(path="/data")]
+ assert folders.to_dict() == {"folders": [{"path": "/data"}]}
+
+ mcp = config_schema.MCPConfig.from_dict(
+ {
+ "mcpServers": {
+ "stdio": {"command": "python"},
+ "http": {"url": "https://example.com"},
+ }
+ }
+ )
+ assert mcp.mcpServers == {
+ "stdio": config_schema.MCPServerStdioConfig(command="python"),
+ "http": config_schema.MCPServerStreamableHttpConfig(
+ url="https://example.com"
+ ),
+ }
+
+
+def test_unknown_fields_survive_resolution_and_merging() -> None:
+ config = MarimoConfig.from_dict(
+ {
+ "future_section": {"value": [1, 2]},
+ "runtime": {"future_setting": None},
+ "experimental": {"multi_column": True},
+ "ai": {
+ "custom_providers": {"gateway": {"future_option": "value"}}
+ },
+ }
+ )
+ merged = merge_config(
+ config.to_dict(), {"experimental": {"debugger": False}}
+ )
+ serialized = merged
+
+ assert serialized["future_section"] == {"value": [1, 2]}
+ assert serialized["runtime"]["future_setting"] is None
+ assert serialized["experimental"] == {
+ "multi_column": True,
+ "debugger": False,
+ }
+ assert serialized["ai"]["custom_providers"] == {
+ "gateway": {"future_option": "value"}
+ }
+ assert MarimoConfig.from_dict(serialized).to_dict() == serialized
+ assert config.to_dict()["experimental"] == {"multi_column": True}
+
+
+def test_unknown_fields_are_copied() -> None:
+ source = {"future_section": {"values": [1]}}
+ config = MarimoConfig.from_dict(source)
+ source["future_section"]["values"].append(2)
+ serialized = config.to_dict()
+ serialized["future_section"]["values"].append(3)
+
+ assert config.to_dict()["future_section"] == {"values": [1]}
+
+
+def test_saving_config_preserves_unknown_fields(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ path = tmp_path / "marimo.toml"
+ path.write_text(
+ '[experimental]\nmulti_column = true\n\n[future_section]\nvalue = "kept"\n'
+ )
+ store = UserConfigStore()
+ monkeypatch.setattr(store, "get_config_path", lambda: str(path))
+
+ saved = store.save_config({"experimental": {"debugger": False}})
+
+ assert saved["experimental"] == {
+ "multi_column": True,
+ "debugger": False,
+ }
+ assert store.read()["experimental"] == {
+ "multi_column": True,
+ "debugger": False,
+ }
+ assert store.read()["future_section"] == {"value": "kept"} # type: ignore[typeddict-item]
+
+
+ ("values", "path"),
+ [
+ ({"save": {"autosave_delay": "fast"}}, "$.save.autosave_delay"),
+ ({"display": {"theme": "invalid"}}, "$.display.theme"),
+ (
+ {"ai": {"models": {"displayed_models": [42]}}},
+ "$.ai.models.displayed_models[0]",
+ ),
+ ],
+)
+def test_conversion_validates_known_fields(
+ values: dict[str, Any], path: str
+) -> None:
+ with pytest.raises(msgspec.ValidationError) as error:
+ MarimoConfig.from_dict(values)
+ assert path in str(error.value)
+
+
+def test_mcp_round_trip_preserves_legacy_input_and_unknown_fields() -> None:
+ servers = {
+ "stdio": {"command": "python", "args": None, "future": {"value": 1}},
+ "http": {"url": "https://example.com", "timeout": 2.5},
+ "both": {"command": "python", "url": "https://example.com"},
+ }
+ config = MarimoConfig.from_dict({"mcp": {"mcpServers": servers}})
+ assert config.mcp.to_dict() == {"mcpServers": servers, "presets": []}
+ assert isinstance(
+ config.mcp.mcpServers["both"], config_schema.MCPServerStdioConfig
+ )
+ assert (
+ config_schema.MCPConfig.from_dict({"mcpServers": servers})
+ == config.mcp
+ )
+ assert servers["stdio"] == {
+ "command": "python",
+ "args": None,
+ "future": {"value": 1},
+ }
+
+
+def test_mcp_missing_transport_fields_is_rejected() -> None:
+ with pytest.raises(msgspec.ValidationError, match="__marimo_transport__"):
+ config_schema.MCPConfig.from_dict(
+ {"mcpServers": {"broken": {"args": []}}}
+ )
+
+
+def test_unknown_fields_in_lists_follow_their_objects() -> None:
+ config = config_schema.FileBrowserConfig.from_dict(
+ {
+ "folders": [
+ {"path": "/first", "future": {"value": [1]}},
+ {"path": "/second", "label": "retained"},
+ ]
+ }
+ )
+ assert isinstance(config.folders, list)
+ config.folders.reverse()
+ assert config.to_dict() == {
+ "folders": [
+ {"path": "/second", "label": "retained"},
+ {"path": "/first", "future": {"value": [1]}},
+ ]
+ }
+ serialized = config.to_dict()
+ serialized["folders"][1]["future"]["value"].append(2)
+ assert config.to_dict()["folders"][1]["future"] == {"value": [1]}
+
+
+def test_metadata_describes_and_hides_secrets() -> None:
+ config = config_schema.OpenAiConfig(
+ api_key="secret", base_url="https://example.com"
+ )
+ assert "secret" not in repr(config)
+ assert dict(config.__rich_repr__()) == {
+ name: getattr(config, name)
+ for name in config.__struct_fields__
+ if name not in {"api_key", "extra_headers"}
+ }
+ schema = msgspec.json.schema(config_schema.OpenAiConfig)["$defs"][
+ "OpenAiConfig"
+ ]
+ assert schema["properties"]["model"]["deprecated"] is True
+ assert (
+ schema["properties"]["api_key"]["description"]
+ == "the OpenAI API key or an `env:` reference"
+ )
+
+
+def test_cache_store_union_uses_struct_conversion() -> None:
+ for store in (
+ {"type": "file", "args": {"path": "/cache"}},
+ [{"type": "file"}, {"type": "redis"}],
+ ):
+ config = config_schema.CacheConfig.from_dict({"store": store})
+ assert config.to_dict() == {"store": store}
+ if isinstance(config.store, list):
+ assert all(
+ isinstance(item, config_schema.StoreConfig)
+ for item in config.store
+ )
+ else:
+ assert isinstance(config.store, config_schema.StoreConfig)
+
+
+ ("cls", "field_name", "settings"),
+ [
+ (config_schema.OpenAiConfig, "extra_headers", {}),
+ (config_schema.MCPServerStdioConfig, "env", {"command": "python"}),
+ (
+ config_schema.MCPServerStreamableHttpConfig,
+ "env",
+ {"url": "https://example.com"},
+ ),
+ (
+ config_schema.MCPServerStreamableHttpConfig,
+ "headers",
+ {"url": "https://example.com"},
+ ),
+ ],
+)
+def test_credential_mappings_are_hidden_from_representations(
+ cls: type[Config], field_name: str, settings: dict[str, Any]
+) -> None:
+ credentials = {"AUTHORIZATION": "credential-mapping-secret"}
+ config = cls.from_dict({**settings, field_name: credentials})
+
+ assert "credential-mapping-secret" not in repr(config)
+ assert "credential-mapping-secret" not in repr(config.__rich_repr__())
+ assert field_name not in dict(config.__rich_repr__())
+ assert config.to_dict()[field_name] == credentials