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.
Adding Lint Rules to marimo
This guide explains how to add new lint rules to marimo's linting system.
Overview
marimo's lint system helps users write better, more reliable notebooks by detecting various issues that could prevent notebooks from running correctly. The system is organized around four severity levels:
- Breaking (MB): Errors that prevent notebook execution
- Runtime (MR): Issues that may cause runtime problems
- Formatting (MF): Style and formatting issues
- WASM (MW): Compatibility issues for WASM/Pyodide notebooks (off by default)
Rule Code Assignment
Rule codes follow a specific pattern: M[severity][number]
Current Code Ranges
- MB001-MB099: Breaking rules
- MR001-MR099: Runtime rules
- MF001-MF099: Formatting rules
- MW001-MW099: WASM compatibility rules (off by default)
Assigning New Codes
When adding a new rule:
- Determine severity: Choose Breaking, Runtime, or Formatting based on impact
- Find next available code: Check existing rules in the appropriate category
- Use sequential numbering: MB005, MB006, etc.
Example assignments:
- MB001: unparsable-cells
- MB002: multiple-definitions
- MB003: cycle-dependencies
- MB004: setup-cell-dependencies
- MF001: general-formatting
- MF002: parse-stdout
- MF003: parse-stderr
Step-by-Step Implementation
1. Create the Rule Class
Create your rule in the appropriate directory:
- Breaking rules:
marimo/_lint/rules/breaking/ - Runtime rules:
marimo/_lint/rules/runtime/ - Formatting rules:
marimo/_lint/rules/formatting/ - WASM rules:
marimo/_lint/rules/wasm/
Template for a new rule:
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
from typing import TYPE_CHECKING
from marimo._lint.diagnostic import Diagnostic, Severity
from marimo._lint.rules.base import LintRule
if TYPE_CHECKING:
from marimo._lint.context import RuleContext
class YourNewRule(LintRule):
"""MB005: Brief description of what this rule checks.
Detailed explanation of what this rule does and why it's important.
This should explain the technical details of how the rule works.
## What it does
Clear, concise explanation of what the rule detects.
## Why is this bad?
Explanation of why this issue is problematic:
- Impact on notebook execution
- Potential for bugs or confusion
- Effect on reproducibility
## Examples
**Problematic:**
```python
# Example of code that violates this rule
bad_code = "example"
```
**Solution:**
```python
# Example of how to fix the violation
good_code = "example"
```
## References
- [Understanding Errors](https://docs.marimo.io/guides/understanding_errors/)
- [Relevant Guide](https://docs.marimo.io/guides/...)
"""
code = "MB005" # Your assigned code
name = "your-rule-name" # Kebab-case name
description = "Brief description for rule listings"
severity = Severity.BREAKING # Or RUNTIME/FORMATTING
fixable = False # True if rule can auto-fix issues
async def check(self, ctx: RuleContext) -> None:
"""Implement your rule logic here."""
# Iterate through notebook cells
for cell in ctx.notebook.cells:
# Your detection logic here
if self._detect_violation(cell):
diagnostic = Diagnostic(
message="Description of the specific violation",
line=cell.lineno,
column=cell.col_offset + 1,
code=self.code,
name=self.name,
severity=self.severity,
fixable=self.fixable,
)
await ctx.add_diagnostic(diagnostic)
def _detect_violation(self, cell) -> bool:
"""Helper method for detection logic."""
# Implement your specific detection logic
return False
2. Register the Rule
Add your rule to the appropriate __init__.py file:
For Breaking rules (marimo/_lint/rules/breaking/__init__.py):
from marimo._lint.rules.breaking.your_file import YourNewRule
BREAKING_RULE_CODES: dict[str, type[LintRule]] = {
"MB001": UnparsableRule,
"MB002": MultipleDefinitionsRule,
"MB003": CycleDependenciesRule,
"MB004": SetupCellDependenciesRule,
"MB005": YourNewRule, # Add your rule here
}
__all__ = [
# ... existing rules ...
"YourNewRule", # Add to exports
"BREAKING_RULE_CODES",
]
3. Create Test Files
a) Create a test notebook file
Create tests/_lint/test_files/your_rule_name.py:
import marimo
__generated_with = "0.15.2"
app = marimo.App()
@app.cell
def _():
# Code that should trigger your rule
problematic_code = "example"
return
@app.cell
def _():
# Additional test cases
return
if __name__ == "__main__":
app.run()
b) Add snapshot test
Add to tests/_lint/test_snapshot.py:
def test_your_rule_snapshot():
"""Test snapshot for your new rule."""
file = "tests/_lint/test_files/your_rule_name.py"
with open(file) as f:
code = f.read()
notebook = parse_notebook(code, filepath=file)
errors = lint_notebook(notebook)
# Format errors for snapshot
error_output = []
for error in errors:
error_output.append(error.format())
snapshot("your_rule_name_errors.txt", "\n".join(error_output))
c) Add unit tests (optional but recommended)
For more rigorous testing, create tests/_lint/test_your_rule.py:
import pytest
from marimo._ast.parse import parse_notebook
from marimo._lint.context import LintContext
from marimo._lint.rules.breaking import YourNewRule
class TestYourNewRule:
"""Test cases for YourNewRule."""
async def test_detects_violation(self):
"""Test that the rule detects violations correctly."""
code = """import marimo
app = marimo.App()
@app.cell
def _():
# Code that should trigger the rule
return
"""
notebook = parse_notebook(code)
ctx = LintContext(notebook)
rule = YourNewRule()
await rule.check(ctx)
diagnostics = await ctx.get_diagnostics()
assert len(diagnostics) > 0
assert diagnostics[0].code == "MB005"
assert diagnostics[0].severity == Severity.BREAKING
async def test_no_false_positives(self):
"""Test that the rule doesn't trigger on valid code."""
code = """import marimo
app = marimo.App()
@app.cell
def _():
# Valid code that should not trigger the rule
return
"""
notebook = parse_notebook(code)
ctx = LintContext(notebook)
rule = YourNewRule()
await rule.check(ctx)
diagnostics = await ctx.get_diagnostics()
assert len(diagnostics) == 0
4. Generate Documentation
The documentation is automatically generated from your rule's docstring. Run:
uv run scripts/generate_lint_docs.py
This will create:
docs/guides/lint_rules/rules/your_rule_name.md- Updated
docs/guides/lint_rules/index.md
5. Run Tests
# Run lint tests
uv run --group test pytest tests/_lint
# Run your specific test
uv run --group test pytest tests/_lint/test_your_rule.py
# Update snapshots if needed
uv run --group test pytest tests/_lint/test_snapshots.py --snapshot-update
Rule Implementation Guidelines
Detection Logic
- Prefer AST analysis over string matching when possible
- Use context information from
RuleContext(notebook, graph, etc.) - Be specific in error messages - help users understand the exact issue
- Consider edge cases - test with various code patterns
Error Messages
- Be descriptive: Explain what the issue is
- Be actionable: Suggest how to fix it
- Be consistent: Follow patterns from existing rules
Good: "Variable 'x' is defined in multiple cells"
Bad: "Multiple definition error"
Performance
- Avoid expensive operations in the hot path
- Cache results when checking multiple cells (add to context if needed)
- Early return when possible
Fixability
Safely fixable errors are applied by default via re-serialization. However,
rules may implement unsafe fixes (mutating the notebook structure) that require
the --unsafe-fixes flag. To do this, implement an async def apply_unsafe_fixes(self, notebook, diagnostics) -> Notebook method in your
rule class, and inherit from UnsafeFixRule instead of LintRule.
Default vs Opt-in Rules
Rules in RULE_CODES are the full set of all rules. Rules in DEFAULT_RULE_CODES are those enabled when no --select is specified.
To make a category off by default (like WASM rules), include it in RULE_CODES but exclude it from DEFAULT_RULE_CODES in marimo/_lint/rules/__init__.py:
# Rules enabled by default (excludes opt-in categories like WASM).
DEFAULT_RULE_CODES: dict[str, type[LintRule]] = (
BREAKING_RULE_CODES | RUNTIME_RULE_CODES | FORMATTING_RULE_CODES
)
# All known rules (including opt-in). Used when --select is provided.
RULE_CODES: dict[str, type[LintRule]] = DEFAULT_RULE_CODES | WASM_RULE_CODES
Users opt in via marimo check --select MW or --select ALL. The resolve_rules() function in rule_selector.py uses DEFAULT_RULE_CODES when no select is specified, and RULE_CODES when it is.
Common Patterns
Checking All Cells
async def check(self, ctx: RuleContext) -> None:
for cell in ctx.notebook.cells:
if self._check_cell(cell):
# Create diagnostic
Using the Dependency Graph
async def check(self, ctx: RuleContext) -> None:
graph = ctx.get_graph()
for cell_id, cell_data in graph.cells.items():
# Analyze dependencies
Testing Best Practices
Snapshot Tests
- Include in snapshot tests for regression protection
- Use realistic examples that demonstrate the rule clearly
- Test edge cases in separate unit tests
Unit Tests
- Test positive cases (rule triggers correctly)
- Test negative cases (no false positives)
- Test edge cases (empty cells, syntax errors, etc.)
- Test multiple violations in one notebook
Test File Structure
tests/_lint/
├── test_files/ # Test notebooks
│ └── your_rule_name.py
├── snapshots/ # Expected outputs
│ └── your_rule_name_errors.txt
├── test_your_rule.py # Unit tests
└── test_snapshots.py # Snapshot tests
Documentation Requirements
Your rule's docstring should include:
- Rule code and brief description in the first line
- ## What it does - Technical explanation
- ## Why is this bad? - Impact explanation
- ## Examples - Code samples (problematic and fixed)
- ## References - Links to relevant documentation
The documentation system will automatically:
- Generate individual rule pages
- Update the main rules index
- Create proper navigation links
- Use human-readable filenames
Review Checklist
Before submitting your rule:
- Rule code follows numbering convention
- Rule is registered in appropriate
__init__.py - Comprehensive docstring with all required sections
- Unit tests cover positive and negative cases
- Snapshot test included
- Documentation generates correctly
- All lint tests pass
- Error messages are clear and actionable
- Performance is reasonable for large notebooks
Examples
Simple Rule Implementation
Example of a simple rule that checks for syntax errors: https://github.com/marimo-team/marimo/pull/6384
Rule Implementation with --unsafe-fixes
Some rules may have "fixes" that mutate the notebook structure. An example of a rule that mutates the notebook structure (i.e. an unsafe fix) by removing empty cells: https://github.com/marimo-team/marimo/pull/6398
Rule Implementation with Log Context
Some parsing issues result in log warnings or errors. An example of a rule that hooks into issued logs can be found here:
Note: Resist intentionally adding log statements such that they trigger lint rules. Log statements should be added only when they provide useful context, on notebook startup.