Configuration - marimo

marimo provides flexible configuration options to customize your development environment. Configuration can be applied globally, per-project, or per-notebook, giving you fine-grained control over editor behavior, runtime settings, code completion, and more.

Configuration Hierarchy

marimo merges configuration from multiple sources in order of precedence:

Script metadata (highest priority) - Embedded in notebook files
Project configuration - pyproject.toml in project directory
User configuration (lowest priority) - ~/.config/marimo/marimo.toml

Settings from higher-priority sources override those from lower-priority sources. Settings configured in pyproject.toml or script metadata cannot be changed through the marimo UI.

User Configuration

User configuration applies globally to all marimo notebooks and is stored in ~/.config/marimo/marimo.toml (or $XDG_CONFIG_HOME/marimo/marimo.toml).

Locating Your Config File

Find your user configuration file:

# Show config file location and current settings
marimo config show

# Show just the config file path
marimo config show | head -n 1

# Describe all available configuration options
marimo config describe

Creating and Editing

marimo creates a config file automatically on first run. You can edit it through: Via UI (Recommended):

Open any notebook: marimo edit
Click settings icon (⚙️) in top-right
Navigate to different configuration tabs
Changes save automatically

Via Text Editor:

# Edit directly
$EDITOR ~/.config/marimo/marimo.toml

Configuration File Format

The marimo.toml file uses TOML format:

marimo.toml

[completion]
activate_on_typing = true
signature_hint_on_typing = false
copilot = "github"

[display]
theme = "light"
code_editor_font_size = 14
cell_output = "below"
default_width = "medium"

[keymap]
preset = "default"  # or "vim"

[runtime]
auto_instantiate = false
on_cell_change = "autorun"
auto_reload = "off"

[save]
autosave = "after_delay"
autosave_delay = 1000
format_on_save = false

[package_management]
manager = "uv"  # or "pip", "poetry", "rye", "pixi"

Project Configuration

Project configuration is stored in pyproject.toml and applies to all notebooks in the project directory (and subdirectories). This is ideal for team settings and ensuring consistent behavior across a codebase.

Setup

Create or edit pyproject.toml in your project root:

pyproject.toml

[tool.marimo.formatting]
line_length = 88  # Black-compatible formatting

[tool.marimo.display]
default_width = "full"
theme = "dark"

[tool.marimo.runtime]
auto_instantiate = false
auto_reload = "lazy"
default_sql_output = "polars"

[tool.marimo.package_management]
manager = "uv"

[tool.marimo.keymap]
preset = "vim"
vimrc = "configs/.vimrc"  # Path relative to pyproject.toml

Project-Specific Paths

marimo resolves relative paths in pyproject.toml relative to the file’s location:

pyproject.toml

[tool.marimo.runtime]
pythonpath = ["src", "lib"]  # Adds project_root/src and project_root/lib to sys.path
dotenv = [".env", ".env.local"]  # Loads environment variables from these files

[tool.marimo.display]
custom_css = ["styles/notebook.css"]  # Custom styling

[tool.marimo.keymap]
vimrc = "configs/.vimrc"  # Load vim keybindings

Configuration Discovery

marimo searches for pyproject.toml by walking up the directory tree from the notebook location:

/home/user/project/
├── pyproject.toml          # ← Found and applied
├── notebooks/
│   └── analysis.py         # ← Opened notebook
└── src/

Script Metadata Configuration

Embed configuration directly in notebook files using PEP 723 script metadata. This has the highest precedence and travels with the notebook.

Adding Script Metadata

Add a special comment block at the top of your notebook:

notebook.py

# /// script
# [tool.marimo.runtime]
# auto_instantiate = false
# on_cell_change = "lazy"
# 
# [tool.marimo.display]
# theme = "dark"
# cell_output = "above"
# ///

import marimo as mo

__generated_with = "0.20.3"
app = mo.App()

@app.cell
def __():
    import pandas as pd
    return pd,

This configuration applies only to this specific notebook and overrides user and project settings.

Use script metadata for:

Notebook-specific display preferences (theme, width)
Disabling auto-instantiate for expensive notebooks
Lazy execution for interactive analysis
Configuration that should travel with the notebook

Configuration Categories

Completion

Control code completion and AI copilots:

[completion]
activate_on_typing = true           # Auto-show completions while typing
signature_hint_on_typing = false    # Show function signatures on trigger only
copilot = "github"                  # Options: false, "github", "codeium", "custom"
codeium_api_key = "your-key"        # For Codeium/Windsurf

See Code Completion for details.

Display

Customize editor appearance:

[display]
theme = "light"                     # Options: "light", "dark", "system"
code_editor_font_size = 14          # Font size in pixels
cell_output = "below"               # Options: "above", "below"
default_width = "medium"            # Options: "normal", "medium", "full", "compact", "columns"
dataframes = "rich"                 # Options: "rich", "plain"
default_table_page_size = 10        # Rows per page in tables
default_table_max_columns = 50      # Max columns to display
reference_highlighting = true       # Highlight variable references
locale = "en-US"                    # Locale for date formatting
custom_css = ["custom.css"]         # Custom CSS files

Formatting

Code formatting options:

[formatting]
line_length = 79  # Max characters per line (default matches PEP 8)

marimo uses Ruff for formatting. Install with:

pip install ruff

Keymap

Keyboard shortcuts and vim mode:

[keymap]
preset = "default"                  # Options: "default", "vim"
vimrc = "path/to/.vimrc"            # Load vim keybindings from file
destructive_delete = false          # Allow deleting cells with content

# Custom keybindings
[keymap.overrides]
"cell.run" = "Ctrl-Enter"
"cell.createBelow" = "Ctrl-b"

See Keyboard Shortcuts for all available actions.

Runtime

Control notebook execution behavior:

[runtime]
auto_instantiate = false            # Auto-run cells on notebook open
auto_reload = "off"                 # Options: "off", "lazy", "autorun"
reactive_tests = true               # Auto-run test functions
on_cell_change = "autorun"          # Options: "autorun", "lazy"
watcher_on_save = "lazy"            # Options: "lazy", "autorun"
output_max_bytes = 8000000          # Max output size (8MB)
std_stream_max_bytes = 1000000      # Max console output (1MB)
default_sql_output = "auto"         # Options: "auto", "polars", "pandas", "native"
default_csv_encoding = "utf-8"      # CSV export encoding
pythonpath = ["src", "lib"]         # Additional Python paths
dotenv = [".env"]                   # Environment variable files to load

Key settings explained:

auto_instantiate: If false, cells don’t run automatically when opening a notebook (useful for expensive computations)
on_cell_change: How dependent cells react when an ancestor changes
- "autorun": Automatically re-run dependent cells
- "lazy": Mark dependent cells as stale without running
auto_reload: Automatically reload modified Python modules
- "off": No auto-reloading
- "lazy": Mark importing cells as stale when modules change
- "autorun": Auto-run importing cells when modules change

See Runtime Configuration for details.

Save

Autosave and formatting:

[save]
autosave = "after_delay"            # Options: "off", "after_delay"
autosave_delay = 1000               # Milliseconds before autosave
format_on_save = false              # Auto-format code on save

Package Management

Package manager preference:

[package_management]
manager = "uv"  # Options: "pip", "uv", "poetry", "rye", "pixi"

See Package Management for details.

Server

Server behavior:

[server]
browser = "default"                 # Or "firefox", "chrome", etc.
follow_symlink = false              # Follow symlinks in static assets
disable_file_downloads = false      # Hide file download button

AI Configuration

AI assistance and copilots:

[ai]
rules = "Prefer polars over pandas"  # Custom AI rules
max_tokens = 2048                     # Max tokens for AI responses
mode = "ask"                          # Options: "ask", "manual", "agent"
inline_tooltip = true                 # Enable inline AI tooltips

[ai.models]
chat_model = "claude-4.5-sonnet"
edit_model = "gpt-4o"
autocomplete_model = "github/copilot"
displayed_models = ["gpt-4o", "claude-4.5-sonnet"]
custom_models = []

# Provider configurations
[ai.open_ai]
api_key = "sk-..."
base_url = "https://api.openai.com/v1"  # Optional

[ai.anthropic]
api_key = "sk-ant-..."

[ai.github]
api_key = "ghp_..."

[ai.github.copilot_settings.http]
proxy = "http://proxy.example.com:8888"
proxyStrictSSL = false

See AI Completion and LLM Providers for details.

Language Servers

Configure LSP servers for enhanced code intelligence:

[language_servers.pylsp]
enabled = true
enable_mypy = true
enable_ruff = true
enable_flake8 = false
enable_pydocstyle = false

[language_servers.basedpyright]
enabled = true

[language_servers.ty]
enabled = false

[language_servers.pyrefly]
enabled = false

See Language Server Protocol for details.

Diagnostics

Error checking and linting:

[diagnostics]
enabled = true        # Show diagnostics in editor
sql_linter = true     # Lint SQL cells

Snippets

Code snippets configuration:

[snippets]
custom_paths = ["~/.marimo/snippets"]
include_default_snippets = true

See Snippets for details.

Experimental Features

Enable preview features:

[experimental]
markdown = true       # Enhanced markdown features
wasm_layouts = true   # WebAssembly layout support

Experimental features may change or be removed in future versions.

Environment Variables

marimo supports environment variables for advanced configuration:

Variable	Description	Default
`MARIMO_OUTPUT_MAX_BYTES`	Max output size before truncation	8,000,000 (8MB)
`MARIMO_STD_STREAM_MAX_BYTES`	Max console output size	1,000,000 (1MB)
`MARIMO_SKIP_UPDATE_CHECK`	Skip version update checks	Not set
`MARIMO_SQL_DEFAULT_LIMIT`	Default SQL query row limit	Not set
`MARIMO_TRACING`	Enable distributed tracing	”false”
`MARIMO_MANAGE_SCRIPT_METADATA`	Manage PEP 723 metadata	”false”

Set environment variables in your shell or .env file:

export MARIMO_OUTPUT_MAX_BYTES=16000000
export MARIMO_SKIP_UPDATE_CHECK=1

Or load from .env files:

pyproject.toml

[tool.marimo.runtime]
dotenv = [".env", ".env.local"]

Prefer configuring output_max_bytes and std_stream_max_bytes in pyproject.toml rather than environment variables for better reproducibility.

Configuration Examples

Team Data Science Setup

pyproject.toml

[tool.marimo.formatting]
line_length = 88  # Black standard

[tool.marimo.display]
default_width = "full"
theme = "system"  # Respect OS theme

[tool.marimo.runtime]
auto_instantiate = false  # Don't auto-run expensive notebooks
on_cell_change = "lazy"   # Manual control over execution
default_sql_output = "polars"  # Team uses Polars
pythonpath = ["src"]
dotenv = [".env"]

[tool.marimo.package_management]
manager = "uv"  # Fast package management

[tool.marimo.ai]
rules = """
Prefer polars over pandas for dataframes.
Use altair for declarative visualizations.
Include type hints on all functions.
"""

Individual Developer Setup

~/.config/marimo/marimo.toml

[completion]
activate_on_typing = true
copilot = "github"

[display]
theme = "dark"
code_editor_font_size = 16

[keymap]
preset = "vim"
vimrc = "~/.vimrc"

[save]
autosave = "after_delay"
autosave_delay = 500  # Fast autosave
format_on_save = true

[ai.open_ai]
api_key = "sk-..."

[language_servers.pylsp]
enabled = true
enable_mypy = true
enable_ruff = true

Expensive Computation Notebook

expensive_analysis.py

# /// script
# [tool.marimo.runtime]
# auto_instantiate = false      # Don't run on open
# on_cell_change = "lazy"       # Manual execution control
# ///

import marimo as mo

Troubleshooting

Settings not taking effect

Check configuration precedence:

Script metadata overrides everything
Project pyproject.toml overrides user config
User marimo.toml is the base

Verify which config is active:

marimo config show

Look for the config file path and current settings.

Can't change settings in UI

If settings are grayed out in the UI, they’re overridden in pyproject.toml or script metadata. Edit those files directly:

# Find project config
find . -name "pyproject.toml"

# Edit it
$EDITOR pyproject.toml

Vim mode not working

Ensure vim preset is set:

[keymap]
preset = "vim"

If using a vimrc file, ensure the path is correct:

# In pyproject.toml, paths are relative to the file
[tool.marimo.keymap]
vimrc = "configs/.vimrc"  # project_root/configs/.vimrc

# In marimo.toml, use absolute paths
[keymap]
vimrc = "/home/user/.vimrc"

Python path not working

Verify pythonpath is set correctly:

pyproject.toml

[tool.marimo.runtime]
pythonpath = ["src", "lib"]  # Relative to pyproject.toml location

Test in a cell:

import sys
print(sys.path)  # Should include your directories

Best Practices

✅ Version control configuration

Do commit:

pyproject.toml - Shared project settings
Script metadata in notebooks - Notebook-specific config

Don’t commit:

~/.config/marimo/marimo.toml - Personal settings
API keys (use environment variables instead)

✅ Share team settings

Use pyproject.toml to ensure consistent behavior:

pyproject.toml

[tool.marimo.formatting]
line_length = 88

[tool.marimo.package_management]
manager = "uv"

[tool.marimo.runtime]
default_sql_output = "polars"

Commit this file so all team members use the same settings.

✅ Use environment variables for secrets

Don’t hardcode API keys in config files:

.env

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

pyproject.toml

[tool.marimo.runtime]
dotenv = [".env"]

Add .env to .gitignore.

Runtime Configuration - Detailed runtime settings
LLM Providers - AI provider configuration
Keyboard Shortcuts - Customizing keybindings
Code Completion - Completion configuration
Language Server Protocol - LSP configuration

Get Started

Core Features

Working with Notebooks

Deployment

Data & Visualization

Editor Features

Advanced Topics

​Configuration Hierarchy

​User Configuration

​Locating Your Config File

​Creating and Editing

​Configuration File Format

​Project Configuration

​Setup

​Project-Specific Paths

​Configuration Discovery

​Script Metadata Configuration

​Adding Script Metadata

​Configuration Categories

​Completion

​Display

​Formatting

​Keymap

​Runtime

​Save

​Package Management

​Server

​AI Configuration

​Language Servers

​Diagnostics

​Snippets

​Experimental Features

​Environment Variables

​Configuration Examples

​Team Data Science Setup

​Individual Developer Setup

​Expensive Computation Notebook

​Troubleshooting

​Best Practices

​Related Documentation

Build docs developers (and LLMs) love

Configuration Hierarchy

User Configuration

Locating Your Config File

Creating and Editing

Configuration File Format

Project Configuration

Setup

Project-Specific Paths

Configuration Discovery

Script Metadata Configuration

Adding Script Metadata

Configuration Categories

Completion

Display

Formatting

Keymap

Runtime

Save

Package Management

Server

AI Configuration

Language Servers

Diagnostics

Snippets

Experimental Features

Environment Variables

Configuration Examples

Team Data Science Setup

Individual Developer Setup

Expensive Computation Notebook

Troubleshooting

Best Practices

Related Documentation