Adopt *.mo.py naming convention for marimo notebooks

[SerPeter]

Proposal

Encourage (and eventually recognize) *_mo.py as the conventional file suffix for marimo notebooks, e.g.,
analysis.mo.py instead of analysis.py.

This is a naming convention, not a format change. The files remain valid Python. The double extension simply
makes marimo notebooks identifiable by filename alone.

Why this matters

1. Visibility in a codebase

In any project mixing regular Python modules with marimo notebooks, there's no way to tell them apart without opening
the file and checking for the app = marimo.App() marker. A *_mo.py suffix makes notebooks immediately
recognizable in file trees, search results, and git log.

2. Targeted tooling configuration

Today, configuring tools differently for notebooks vs regular Python requires manual file lists. With a distinct suffix:

• Linters (ruff, flake8) can apply notebook-specific rules via glob:
  [tool.ruff.per-file-overrides] "_.mo.py" = { ... }
• Pre-commit hooks can run marimo lint only on notebook files
• CI/CD can gate notebook-specific checks without maintaining an explicit allowlist
• Editors can apply different formatting, folding, or LSP settings per file pattern

3. Agent and LLM workflows

AI agents working in a codebase need to distinguish notebooks from regular modules to apply the right editing
patterns (reactive cells,mo.* output rules, no cross-cell variable reuse). A filename convention is the simplest, most universal signal,
it works across every tool and context without parsing.

Compatibility

• *_mo.py files are still valid .py files, Python, pip, and all existing tools handle them normally
• This mirrors established conventions: *.test.py, *.spec.ts, *.stories.tsx, *.module.css
• The marimo CLI (marimo edit, marimo run) would accept *_mo.py files with no changes needed
• Existing *.py notebooks continue to work — this is opt-in adoption, not a breaking change

What "adopt" could look like

1. Documentation: recommend *_mo.py in the getting-started guide and marimo init output
2. CLI defaults: marimo new analysis creates analysis.mo.py
3. Detection: treat _.mo.py as a strong signal for marimo-specific behavior (lint rules, file watchers, etc.), falling back to content-based detection for plain *.py files
4. Template repos and examples: use the convention in official examples

Edits:

• Changed *.mo.py to _mo.py

[dmadisetti]

The files remain valid Python.

This is actually incorrect. You cannot import a file like this, and I think python file.mo.py doesn't work either.

But a good idea! We have thought about this and have even considered _mo.py as a convention: marimo-team/meps#10 (for additional points against .mo.py as well). _mo.py is a bit of an unofficial convention and has special behavior in the Vscode extension and marimo-jupyter-extension.

But since marimo files really are python (they can bootstrap themselves), I don't think sharing the namespace is that bad.

[SerPeter]

Ah my bad. Normally I only import from other notebooks so I didn't catch that, so *_mo.py it is than.

Is there any reason for the PR being stale for the last half year?
I think it would still be a great idea to have this so that it's easier to detect in CI or other tools. Of course this can always be followed by just the user himself, but for me it took some time and headache before coming on this. Also I do believe that all software should have strong defaults / conventions to enable best practices straigth out of the box.