marimo config

Manage marimo configuration settings

marimo config

Manage marimo configuration settings including user preferences and project-specific overrides.

Usage

marimo config <COMMAND>

Commands

• show - Display current configuration
• describe - Show documentation for all config options

---

marimo config show

Display the current marimo configuration including user settings and project overrides.

Usage

marimo config show

Output

The command displays:

1. Project overrides - Settings from the nearest pyproject.toml (if any)
2. User config - Global user settings from the user config file

Examples

# Show current configuration
marimo config show

Example output:

📁 Project overrides from /path/to/pyproject.toml

[tool.marimo]
autosave = "on_idle"
autosave_delay = 2000

🏠 User config from ~/.marimo.toml

[completion]
autocomplete = true
activate_on_typing = true
copliot = false

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

[runtime]
auto_instantiate = true

Configuration Hierarchy

marimo uses a two-level configuration system:

1. User config - Global settings in ~/.marimo.toml
2. Project config - Overrides in pyproject.toml under [tool.marimo]

Project settings take precedence over user settings.

---

marimo config describe

Show detailed documentation for all available configuration options.

Usage

marimo config describe

Output

Displays comprehensive documentation for every config option including:

• Configuration section names
• Available settings
• Data types
• Descriptions

Examples

# View all config documentation
marimo config describe

Example output:

# marimo configuration

[completion]
  autocomplete: bool
  activate_on_typing: bool
  copilot: bool

[save]
  autosave: Literal['off', 'after_delay', 'on_idle']
  autosave_delay: int
  format_on_save: bool
  module_autoreload: bool

[runtime]
  auto_instantiate: bool
  on_cell_change: Literal['lazy', 'autorun']
  ...

---

Configuration File Locations

User Configuration

Location: ~/.marimo.toml (or platform-specific config directory)

Create/Edit:

# The file is created automatically when you run marimo
# Edit it directly with your preferred editor
vim ~/.marimo.toml

Project Configuration

Location: pyproject.toml in your project directory

Format:

[tool.marimo]
autosave = "on_idle"
autosave_delay = 2000
format_on_save = true

Common Configuration Options

Autosave Settings

[save]
autosave = "after_delay"  # Options: "off", "after_delay", "on_idle"
autosave_delay = 1000     # Milliseconds
format_on_save = false

Code Completion

[completion]
autocomplete = true
activate_on_typing = true
copilot = false

Runtime Behavior

[runtime]
auto_instantiate = true
on_cell_change = "autorun"  # Options: "lazy", "autorun"

Server Settings

[server]
browser = "default"  # Or specify browser command
host = "127.0.0.1"
port = 2718

Display Settings

[display]
theme = "light"  # Options: "light", "dark", "system"
code_editor_font_size = 14
cell_output = "above"  # Options: "above", "below"

Examples

View Current Settings

# See what configuration is active
marimo config show

Learn About Available Options

# View all configuration options and their types
marimo config describe

Set Up Project-Specific Config

1. Create or edit pyproject.toml in your project:

[tool.marimo]
autosave = "on_idle"
format_on_save = true

2. Verify the settings:

marimo config show

Configure User Defaults

1. Edit your user config file:

vim ~/.marimo.toml

2. Add your preferences:

[completion]
autocomplete = true
copilot = true

[save]
autosave = "after_delay"
format_on_save = true

[display]
theme = "dark"

3. Verify:

marimo config show

Tips

• Use marimo config show to verify your settings are loaded correctly
• Use marimo config describe to discover available options
• Project configs override user configs - great for team settings
• User configs apply to all notebooks by default
• TOML format is simple and human-readable
• Configuration files are created automatically on first run

Configuration in Practice

Team Collaboration

Add to your project’s pyproject.toml:

[tool.marimo]
# Ensure consistent formatting across the team
format_on_save = true
autosave = "on_idle"

# Consistent runtime behavior
[tool.marimo.runtime]
auto_instantiate = true

Personal Preferences

Set in ~/.marimo.toml:

[display]
theme = "dark"
code_editor_font_size = 16

[completion]
copilot = true

Related Commands

• marimo edit - Start editing with your config
• marimo run - Run notebooks with your config