Skip to content

Configuration reference

All configuration options are listed below, grouped by category. For configuration file syntax, examples, and precedence, see the configuration guide. You can also browse configuration options in the terminal with marimo config describe. Sensitive configuration options are treated as secret and won’t be displayed in terminal output.

Completion

Configuration for code completion.

completion.activate_on_typing

if False, completion won't activate until the completion hotkey is entered

Type: bool

Default: True

completion.signature_hint_on_typing

if False, signature hint won't be shown when typing

Type: bool

Default: False

completion.copilot

one of "github" or "custom"

Type: bool | Literal['custom', 'github']

Default: False

completion.auto_close_pairs

if False, typing an opening bracket, parenthesis, or quote will not automatically insert the closing character

Type: bool

Default: True

completion.api_key

Deprecated Sensitive

Deprecated completion API key. Use an AI provider configuration instead.

Type: str | None

completion.model

Deprecated

Deprecated completion model. Use ai.models.autocomplete_model instead.

Type: str | None

completion.base_url

Deprecated

Deprecated completion API endpoint. Use an AI provider configuration instead.

Type: str | None

Display

Configuration for display.

display.theme

"light", "dark", or "system"

Type: Literal['dark', 'light', 'system']

Default: 'light'

display.code_editor_font_size

font size for the code editor

Type: int

Default: 14

display.cell_output

"above" or "below"

Type: Literal['above', 'below']

Default: 'below'

display.default_width

Default notebook width.

Type: Literal['columns', 'compact', 'full', 'medium', 'normal']

Default: 'medium'

display.dataframes

"rich" or "plain"

Type: Literal['plain', 'rich']

Default: 'rich'

display.custom_css

list of paths to custom CSS files

Type: list[str]

display.default_table_page_size

default number of rows to display in tables

Type: int

Default: 10

display.default_table_max_columns

default maximum number of columns to display in tables

Type: int

Default: 50

display.reference_highlighting

if True, highlight reactive variable references

Type: bool

Default: True

display.code_lens

if True, show inline icons in cell editors linking datasources, storage buckets, and caches to their panels

Type: bool

Default: True

display.locale

locale for date formatting and internationalization (e.g., "en-US", "en-GB", "de-DE")

Type: str | None

Formatting

Configuration for code formatting.

formatting.line_length

max line length

Type: int

Default: 79

formatting.infer_types

infer type annotations for cell parameters on save

Type: Literal['jedi', 'off']

Default: 'off'

Keymap

Configuration for keymaps.

keymap.preset

one of "default" or "vim"

Type: Literal['default', 'vim']

Default: 'default'

keymap.overrides

a dict of keymap actions to their keymap override

Type: dict[str, str]

Default: {}

keymap.vimrc

path to a vimrc file to load keymaps from

Type: str | None

keymap.destructive_delete

if True, allows deleting cells with content.

Type: bool

Runtime

Configuration for runtime.

runtime.auto_instantiate

if False, cells won't automatically run on startup. This only applies when editing a notebook, and not when running as an application.

Type: bool

Default: False

runtime.auto_reload

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.

Type: Literal['autorun', 'lazy', 'off']

Default: 'off'

runtime.reactive_tests

If True, automatically run pytest on cells containing only test functions and test classes.

Type: bool

Default: True

runtime.on_cell_change

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.

Type: Literal['autorun', 'lazy']

Default: 'autorun'

runtime.watcher_on_save

how to handle file changes when saving. "lazy" marks affected cells as stale, "autorun" automatically runs affected cells.

Type: Literal['autorun', 'lazy']

Default: 'lazy'

runtime.output_max_bytes

the maximum size in bytes of cell outputs; larger values may affect frontend performance

Type: int

Default: 8000000

runtime.serve_cached_sessions_in_apps

if True, initialize applications with session cache.

Type: bool

Default: False

runtime.std_stream_max_bytes

the maximum size in bytes of console outputs; larger values may affect frontend performance

Type: int

Default: 1000000

runtime.pythonpath

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.

Type: list[str]

Default: []

runtime.dotenv

Sensitive

Override .env discovery with a list of files to load. Use an empty list to skip .env loading entirely. In project settings and script metadata, paths are relative to the project folder, or the notebook's folder if there is no project. In user settings, paths must be absolute.

Type: list[str]

runtime.sql_default_limit

Default maximum number of SQL result rows when a query has no LIMIT. Must be non-negative; None means no limit.

Type: int | None

runtime.default_sql_output

the default output format for SQL queries. Can be one of: "auto", "native", "polars", "lazy-polars", or "pandas".

Type: Literal['auto', 'lazy-polars', 'native', 'pandas', 'polars']

Default: 'auto'

runtime.default_auto_download

an Optional list of export types to automatically snapshot your notebook as: html, markdown, ipynb.

Type: list[Literal['html', 'ipynb', 'markdown']]

Default: []

runtime.default_csv_encoding

the default encoding for CSV exports.

Type: str

Default: 'utf-8'

runtime.show_tracebacks

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.

Type: bool

Default: False

runtime.execution_type

Cell declaration handling: relaxed or strict.

Type: Literal['relaxed', 'strict']

runtime.cache_cells

Enable experimental automatic cell caching.

Type: bool

Default: False

runtime.pin_modules

Pin imported modules when caching cells.

Type: bool

Default: True

Save

Configuration for saving.

save.autosave

one of "off" or "after_delay"

Type: Literal['after_delay', 'off']

Default: 'after_delay'

save.autosave_delay

Delay in milliseconds before automatically saving.

Type: int

Default: 1000

save.format_on_save

if True, format the code on save

Type: bool

Default: False

Server

Configuration for the server.

server.host

Host to bind to.

Type: str

Default: '127.0.0.1'

server.port

Port to bind to (0-65535). If unset or 0, find an available port.

Type: int | None

Default: None

server.proxy

Address of the reverse proxy.

Type: str | None

Default: None

server.base_url

Base URL for the server, starting with / and without a trailing slash.

Type: str

Default: ''

server.allow_origins

Allowed origins for HTTP and WebSocket connections.

Type: list[str]

Default: []

server.headless

Do not launch a browser.

Type: bool

Default: False

server.watch

Watch notebook files for changes; reload code in edit mode or the application in run mode.

Type: bool

Default: False

server.skew_protection

Enable protection against frontend and server version mismatches.

Type: bool

Default: True

server.timeout

Shut down after this many minutes without a connection.

Type: float | None

Default: None

server.session_ttl

Seconds before closing a disconnected session. Defaults to unlimited in edit mode and 120 in run mode; null means unlimited.

Type: int | None

server.token

Enable token authentication. Defaults to true in edit mode and false in run mode.

Type: bool

server.token_password

Sensitive

Password used for token authentication. Mutually exclusive with token_password_file.

Type: str | None

Default: None

server.token_password_file

Sensitive

File containing the token password, or - to read from stdin. Mutually exclusive with token_password.

Type: str | None

Default: None

server.include_code

Send notebook source code to clients in run mode. Edit mode always includes code.

Type: bool

Default: False

server.redirect_console_to_browser

Redirect console output to the browser. This option only applies to run mode. Edit mode always redirects output to the browser.

Type: bool

Default: False

server.skip_update_check

Skip checking for marimo updates when starting the editor.

Type: bool

Default: False

Only send session cookies over HTTPS. Enable when serving behind TLS.

Type: bool

Default: False

Use partitioned cookies for cross-site HTTPS embeds. Implies SameSite=None and Secure.

Type: bool

Default: False

server.session_secret

Sensitive

Secret used to sign session cookies and to derive the default marimo run auth token. Set a stable value to preserve sessions and tokens across restarts or replicas; otherwise a random secret is generated per process.

Type: str | None

Default: None

server.browser

the web browser to use. "default" or a browser registered with Python's webbrowser module (eg, "firefox" or "chrome")

Type: Literal['default'] | str

Default: 'default'

if true, the server will follow symlinks it finds inside its static assets directory.

Type: bool

Default: False

server.disable_file_downloads

if true, the file download button will be hidden in the file explorer.

Type: bool

Default: False

server.transport

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. The terminal and LSP still require WebSockets.

Type: Literal['sse', 'websocket']

Package management

Configuration options for package management.

package_management.manager

the package manager to use

Type: Literal['pip', 'pixi', 'poetry', 'rye', 'uv']

Default: Dynamic (determined at runtime).

AI

Configuration options for AI.

ai.enabled

if False, hide AI actions and panels in the marimo UI

Type: bool

Default: True

ai.rules

custom rules to include in all AI completion prompts

Type: str

Default: ''

ai.max_tokens

the maximum number of tokens to use in AI completions

Type: int | None

Default: None

ai.mode

notebook access for the built-in assistant: "ask" (read only), "agent" (suggest edits), or "code_mode" (full access). Defaults to "ask".

Type: Literal['agent', 'ask', 'code_mode', 'manual']

Default: 'ask'

ai.inline_tooltip

if True, enable inline AI tooltip suggestions

Type: bool

ai.allow_provider_config

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.

Type: bool

Default: True

ai.models

the models to use for AI completions

Type: table

Default: See defaults below.

ai.models.chat_model

the model to use for chat completions

Type: str | None

Default: None

ai.models.edit_model

the model to use for edit completions

Type: str | None

Default: None

ai.models.autocomplete_model

the model to use for code completion/autocomplete

Type: str | None

Default: None

ai.models.displayed_models

a list of models to display in the UI

Type: list[str]

Default: []

ai.models.custom_models

a list of custom models to use that are not from the default list

Type: list[str]

Default: []

ai.open_ai

the OpenAI config

Type: table

ai.open_ai.api_key

Sensitive

the OpenAI API key or an env: reference

Type: str

ai.open_ai.base_url

the base URL for the API

Type: str

ai.open_ai.project

the project ID for the OpenAI API

Type: str

ai.open_ai.ssl_verify

Whether to verify TLS certificates for the API client.

Type: bool

ai.open_ai.ca_bundle_path

custom ca bundle to be used for verifying SSL certificates. Used to create custom SSL context for httpx client

Type: str

ai.open_ai.client_pem

Path to a client PEM certificate for authenticating API requests.

Type: str

ai.open_ai.extra_headers

Sensitive

extra headers to be passed to the OpenAI client

Type: dict[str, str]

ai.open_ai.model

Deprecated

Deprecated chat model. Use ai.models.chat_model instead.

Type: str

ai.anthropic

the Anthropic config

Type: table

ai.anthropic.api_key

Sensitive

the Anthropic API key or an env: reference

Type: str

ai.google

the Google AI config

Type: table

ai.google.api_key

Sensitive

the Google AI API key or an env: reference

Type: str

ai.bedrock

the Bedrock config

Type: table

ai.bedrock.profile_name

the AWS profile to use

Type: str

ai.bedrock.region_name

the AWS region to use

Type: str

ai.bedrock.aws_access_key_id

Sensitive

the AWS access key ID

Type: str

ai.bedrock.aws_secret_access_key

Sensitive

the AWS secret access key

Type: str

ai.azure

the Azure config

Type: table

ai.azure.api_key

Sensitive

the OpenAI API key or an env: reference

Type: str

ai.azure.base_url

the base URL for the API

Type: str

ai.azure.project

the project ID for the OpenAI API

Type: str

ai.azure.ssl_verify

Whether to verify TLS certificates for the API client.

Type: bool

ai.azure.ca_bundle_path

custom ca bundle to be used for verifying SSL certificates. Used to create custom SSL context for httpx client

Type: str

ai.azure.client_pem

Path to a client PEM certificate for authenticating API requests.

Type: str

ai.azure.extra_headers

Sensitive

extra headers to be passed to the OpenAI client

Type: dict[str, str]

ai.azure.model

Deprecated

Deprecated chat model. Use ai.models.chat_model instead.

Type: str

ai.ollama

the Ollama config

Type: table

ai.ollama.api_key

Sensitive

the OpenAI API key or an env: reference

Type: str

ai.ollama.base_url

the base URL for the API

Type: str

ai.ollama.project

the project ID for the OpenAI API

Type: str

ai.ollama.ssl_verify

Whether to verify TLS certificates for the API client.

Type: bool

ai.ollama.ca_bundle_path

custom ca bundle to be used for verifying SSL certificates. Used to create custom SSL context for httpx client

Type: str

ai.ollama.client_pem

Path to a client PEM certificate for authenticating API requests.

Type: str

ai.ollama.extra_headers

Sensitive

extra headers to be passed to the OpenAI client

Type: dict[str, str]

ai.ollama.model

Deprecated

Deprecated chat model. Use ai.models.chat_model instead.

Type: str

ai.github

the GitHub Copilot config

Type: table

ai.github.api_key

Sensitive

a GitHub Copilot token or an env: reference

Type: str

ai.github.base_url

the base URL for the GitHub Copilot API

Type: str

ai.github.copilot_settings

configuration settings for GitHub Copilot LSP. Supports settings like http (proxy configuration), telemetry, and github-enterprise (enterprise URI).

Type: dict[str, Any]

ai.openrouter

the OpenRouter config

Type: table

ai.openrouter.api_key

Sensitive

the OpenAI API key or an env: reference

Type: str

ai.openrouter.base_url

the base URL for the API

Type: str

ai.openrouter.project

the project ID for the OpenAI API

Type: str

ai.openrouter.ssl_verify

Whether to verify TLS certificates for the API client.

Type: bool

ai.openrouter.ca_bundle_path

custom ca bundle to be used for verifying SSL certificates. Used to create custom SSL context for httpx client

Type: str

ai.openrouter.client_pem

Path to a client PEM certificate for authenticating API requests.

Type: str

ai.openrouter.extra_headers

Sensitive

extra headers to be passed to the OpenAI client

Type: dict[str, str]

ai.openrouter.model

Deprecated

Deprecated chat model. Use ai.models.chat_model instead.

Type: str

ai.wandb

the Weights & Biases config

Type: table

ai.wandb.api_key

Sensitive

the OpenAI API key or an env: reference

Type: str

ai.wandb.base_url

the base URL for the API

Type: str

ai.wandb.project

the project ID for the OpenAI API

Type: str

ai.wandb.ssl_verify

Whether to verify TLS certificates for the API client.

Type: bool

ai.wandb.ca_bundle_path

custom ca bundle to be used for verifying SSL certificates. Used to create custom SSL context for httpx client

Type: str

ai.wandb.client_pem

Path to a client PEM certificate for authenticating API requests.

Type: str

ai.wandb.extra_headers

Sensitive

extra headers to be passed to the OpenAI client

Type: dict[str, str]

ai.wandb.model

Deprecated

Deprecated chat model. Use ai.models.chat_model instead.

Type: str

ai.opencode_go

the OpenCode Go config

Type: table

ai.opencode_go.api_key

Sensitive

the OpenAI API key or an env: reference

Type: str

ai.opencode_go.base_url

the base URL for the API

Type: str

ai.opencode_go.project

the project ID for the OpenAI API

Type: str

ai.opencode_go.ssl_verify

Whether to verify TLS certificates for the API client.

Type: bool

ai.opencode_go.ca_bundle_path

custom ca bundle to be used for verifying SSL certificates. Used to create custom SSL context for httpx client

Type: str

ai.opencode_go.client_pem

Path to a client PEM certificate for authenticating API requests.

Type: str

ai.opencode_go.extra_headers

Sensitive

extra headers to be passed to the OpenAI client

Type: dict[str, str]

ai.opencode_go.model

Deprecated

Deprecated chat model. Use ai.models.chat_model instead.

Type: str

ai.custom_providers

a dict of custom OpenAI-compatible providers

Type: dict[str, table]

Default: {}

ai.custom_providers.<name>.api_key

Sensitive

the OpenAI API key or an env: reference

Type: str

ai.custom_providers.<name>.base_url

the base URL for the API

Type: str

ai.custom_providers.<name>.project

the project ID for the OpenAI API

Type: str

ai.custom_providers.<name>.ssl_verify

Whether to verify TLS certificates for the API client.

Type: bool

ai.custom_providers.<name>.ca_bundle_path

custom ca bundle to be used for verifying SSL certificates. Used to create custom SSL context for httpx client

Type: str

ai.custom_providers.<name>.client_pem

Path to a client PEM certificate for authenticating API requests.

Type: str

ai.custom_providers.<name>.extra_headers

Sensitive

extra headers to be passed to the OpenAI client

Type: dict[str, str]

ai.custom_providers.<name>.model

Deprecated

Deprecated chat model. Use ai.models.chat_model instead.

Type: str

ai.open_ai_compatible

Deprecated

the OpenAI-compatible config (deprecated, use custom_providers)

Type: table

ai.open_ai_compatible.api_key

Deprecated Sensitive

the OpenAI API key or an env: reference

Type: str

ai.open_ai_compatible.base_url

Deprecated

the base URL for the API

Type: str

ai.open_ai_compatible.project

Deprecated

the project ID for the OpenAI API

Type: str

ai.open_ai_compatible.ssl_verify

Deprecated

Whether to verify TLS certificates for the API client.

Type: bool

ai.open_ai_compatible.ca_bundle_path

Deprecated

custom ca bundle to be used for verifying SSL certificates. Used to create custom SSL context for httpx client

Type: str

ai.open_ai_compatible.client_pem

Deprecated

Path to a client PEM certificate for authenticating API requests.

Type: str

ai.open_ai_compatible.extra_headers

Deprecated Sensitive

extra headers to be passed to the OpenAI client

Type: dict[str, str]

ai.open_ai_compatible.model

Deprecated

Deprecated chat model. Use ai.models.chat_model instead.

Type: str

Language servers

Configuration options for language servers.

language_servers.pylsp

the pylsp config

Type: table

Default: See defaults below.

language_servers.pylsp.enabled

Enable this language server.

Type: bool

Default: False

language_servers.pylsp.enable_mypy

Enable mypy diagnostics in pylsp.

Type: bool

Default: True

language_servers.pylsp.enable_ruff

Enable ruff diagnostics in pylsp.

Type: bool

Default: True

language_servers.pylsp.enable_flake8

Enable flake8 diagnostics in pylsp.

Type: bool

Default: False

language_servers.pylsp.enable_pydocstyle

Enable pydocstyle diagnostics in pylsp.

Type: bool

Default: False

language_servers.pylsp.enable_pylint

Enable pylint diagnostics in pylsp.

Type: bool

Default: False

language_servers.pylsp.enable_pyflakes

Enable pyflakes diagnostics in pylsp.

Type: bool

Default: False

language_servers.basedpyright

the basedpyright config

Type: table

language_servers.basedpyright.enabled

Enable this language server.

Type: bool

language_servers.ty

the ty config

Type: table

language_servers.ty.enabled

Enable this language server.

Type: bool

language_servers.pyrefly

the pyrefly config

Type: table

language_servers.pyrefly.enabled

Enable this language server.

Type: bool

Diagnostics

Configuration options for diagnostics.

diagnostics.enabled

if True, diagnostics will be shown in the editor

Type: bool

diagnostics.sql_linter

if True, SQL cells will have linting enabled

Type: bool

Default: True

Lint

Configuration for lint rule selection.

lint.select

list of rule code prefixes that replaces the default enabled set. Use "ALL" to select all rules. Example: ["MB", "MR001"]

Type: list[str]

Default: []

lint.ignore

list of rule code prefixes to remove from the enabled set.

Type: list[str]

Default: []

Experimental

Experimental

Configuration for experimental features.

experimental.markdown

Experimental

Enable experimental Markdown notebook features.

Type: bool

experimental.wasm_layouts

Experimental

Enable experimental layouts in WebAssembly notebooks.

Type: bool

experimental.external_agents

Deprecated Experimental

Deprecated; prefer marimo pair. Enable external agents such as Claude Code and Codex.

Type: bool

experimental.isolate_apps

Experimental

Run applications in separate processes.

Type: bool

Default: False

experimental.debugger

Experimental

Enable live debugging with gutter breakpoints and pdb.

Type: bool

Default: False

experimental.line_timing

Experimental

Highlight the active line and show per-line execution timing.

Type: bool

Default: False

experimental.execution_type

Experimental

Experimental cell declaration handling: relaxed or strict.

Type: Literal['relaxed', 'strict']

Default: 'relaxed'

Snippets

Configuration for snippets.

snippets.custom_paths

Paths to directories containing custom snippets.

Type: list[str]

Default: []

snippets.include_default_snippets

Include the built-in snippets.

Type: bool

Default: True

Datasources

Configuration for datasources panel.

datasources.auto_discover_schemas

if True, include schemas in the datasource

Type: bool | Literal['auto']

datasources.auto_discover_tables

if True, include tables in the datasource

Type: bool | Literal['auto']

datasources.auto_discover_columns

if True, include columns & table metadata in the datasource

Type: bool | Literal['auto']

File browser

Configuration for the file browser panel.

file_browser.folders

additional absolute folders to show in the file browser

Type: list[table]

Default: []

file_browser.folders[].path

the absolute path to the folder

Type: str

Default: Required

file_browser.folders[].name

an optional display name for the folder

Type: str | None

Default: None

Sharing

Configuration for sharing features.

sharing.html

if False, HTML sharing options will be hidden from the UI

Type: bool

sharing.wasm

if False, WebAssembly sharing options will be hidden from the UI

Type: bool

sharing.molab

if False, molab sharing options will be hidden from the UI

Type: bool

MCP

Configuration for MCP servers

mcp.mcpServers

Named MCP server configurations.

Type: dict[str, table | table]

Default: {}

mcp.mcpServers.<name>.command (stdio)

Command used to launch the MCP server.

Type: str

Default: Required

mcp.mcpServers.<name>.args (stdio)

Arguments passed to the MCP server command.

Type: list[str] | None

mcp.mcpServers.<name>.env (stdio)

Sensitive

Environment variables supplied to the MCP server.

Type: dict[str, str] | None

mcp.mcpServers.<name>.disabled (stdio)

Disable this MCP server.

Type: bool | None

mcp.mcpServers.<name>.url (http)

URL of the streamable HTTP MCP server.

Type: str

Default: Required

mcp.mcpServers.<name>.headers (http)

Sensitive

HTTP headers sent to the MCP server.

Type: dict[str, str] | None

mcp.mcpServers.<name>.timeout (http)

Timeout in seconds for MCP server requests.

Type: float | None

mcp.mcpServers.<name>.env (http)

Sensitive

Environment variables used by the MCP server configuration.

Type: dict[str, str] | None

mcp.mcpServers.<name>.disabled (http)

Disable this MCP server.

Type: bool | None

mcp.presets

Built-in MCP server presets to enable.

Type: list[Literal['context7', 'marimo']]

Default: []

Venv

Configuration for an external Python environment in edit mode.

venv.path

path to a virtualenv directory (absolute or relative to pyproject.toml)

Type: str | None

Default: None

venv.writable

if true, marimo will manage script metadata (inline dependencies). Defaults to false.

Type: bool

Default: False

Cache

Configuration for caching.

cache.verification

Cache signature verification posture: off, on, or strict.

Type: Literal['off', 'on', 'strict']

Default: 'off'

cache.store

Backing cache store, or a list of stores composed into a tiered store.

Type: list[table] | table | None

Default: None

cache.store[].type

Cache store backend or installed entry-point name.

Type: Literal['file', 'redis', 'rest', 'tiered'] | str

Default: 'file'

cache.store[].args

Keyword arguments passed to the cache store constructor.

Type: dict[str, Any]

Default: {}

cache.store.type

Cache store backend or installed entry-point name.

Type: Literal['file', 'redis', 'rest', 'tiered'] | str

Default: 'file'

cache.store.args

Keyword arguments passed to the cache store constructor.

Type: dict[str, Any]

Default: {}

cache.loader

Default loader for mo.persistent_cache.

Type: Literal['json', 'lazy', 'pickle'] | str

Default: 'lazy'

Signing

Cache-signing trust and identity.

signing.trusted_signers

Trusted key fingerprints (SHA256:) mapped to advisory labels. Trust permits code execution when restoring cached Python objects.

Type: dict[str, str]

Default: {}

signing.private_key_path

Sensitive

Absolute path to this machine's private signing key. Not exposed to the frontend.

Type: str | None

Default: None