marimo-dev

Build Python packages from Marimo notebooks.

Why this exists

Marimo notebooks are excellent for development - they manage dependencies automatically, provide instant feedback, and let you import functions between notebooks without configuration. But publishing requires traditional Python packages with proper module structure and __init__.py files.

marimo-dev bridges this gap. It extracts decorated functions and classes from your notebooks and writes them to clean Python modules, leaving behind the exploratory code, UI elements, and notebook-specific logic.

Quick start

uv init --lib my-project
cd my-project
uv add marimo marimo-dev
mkdir notebooks

Create notebooks/a_core.py:

import marimo
app = marimo.App()

@app.function
def greet(name:str="World"):
    "Return a greeting"
    return f"Hello, {name}!"

Build and publish:

md build
md publish --test

Project structure

my-project/
├── pyproject.toml
├── notebooks/
│   ├── a_core.py      # letter prefix avoids collision with 'core' package
│   ├── b_utils.py     # avoids collision with 'utils' package
│   └── XX_draft.py    # XX_ prefix = ignored during build
├── src/               # generated by md build
│   └── my_project/
│       ├── __init__.py 
│       ├── core.py    # letter prefix stripped
│       └── utils.py
└── docs/              # generated by md build
    └── llms.txt       # API signatures for LLM consumption

Module naming

Prefix notebooks with letters (a_, b_, c_) to avoid name collisions with common packages like requests, utils, or core. The prefix is stripped in the built package.

During development, import from other notebooks using their full names:

from a_core import greet

marimo-dev rewrites these to relative imports in the built package:

from .core import greet

What gets exported

Only self-contained functions and classes are exported. A self-contained function must: reference no variables outside its scope (except from the setup cell), and be the only function in its cell. See reusing functions for details. Everything else - test code, UI elements, exploratory cells - stays in your notebooks.

Hash pipe directives

Control export and documentation behavior with #| directives on the line immediately after a decorator:

@app.function
#| nodoc
def helper(): 
    pass  # exported but not in llms.txt

@app.function
#| internal
def _private(): 
    pass  # not added to __all__

@app.function
#| nodoc internal
def _helper(): 
    pass  # neither exported nor documented

Documentation style

Use inline comments for parameter documentation:

@app.function
def add(
    a:int, # first number
    b:int, # second number
)->int:    # sum of a and b
    "Add two numbers"
    return a + b

These comments appear in llms.txt, making your API documentation useful for LLM-assisted coding.

Configuration

Add to pyproject.toml to override defaults:

[tool.marimo-dev]
nbs = "notebooks"           # notebook directory (default: "notebooks")
out = "src"                 # output directory (default: "src")
docs = "docs"               # docs directory (default: "docs")
decorators = ["app.function", "app.class_definition"]  # export markers
skip_prefixes = ["XX_", "test_"]  # ignore these files

Commands

md build              # build package from notebooks
md publish --test     # publish to Test PyPI
md publish            # publish to PyPI
md tidy               # remove __pycache__ and cache files
md nuke               # remove all build artifacts (dist, docs, src, temp*)

If you make a temp folder it will be explicitly removed when running md nuke

Dependencies

Marimo manages package dependencies automatically through its package tab. You do not need to manually maintain pyproject.toml dependencies during development.

When you build, ensure your pyproject.toml includes all packages your exported functions import.

Requirements

• Python 3.12+
• marimo
• uv

Tips

• Update version in pyproject.toml before publishing
• Use uv sync --upgrade to update dependencies
• Use uv cache clean if you encounter caching issues
• Rebuild takes ~18ms, so you can run md build frequently during development