Skip to main content
marimo provides tools to convert Jupyter notebooks (.ipynb) and other formats to reactive marimo notebooks.

​
Convert Command

The marimo convert command transforms various formats into marimo notebooks.

​
Basic Conversion

# Convert Jupyter notebook
marimo convert notebook.ipynb -o notebook.py

# Convert and print to stdout
marimo convert notebook.ipynb

# Auto-accept all prompts
marimo -y convert notebook.ipynb -o notebook.py
After conversion, open the notebook with:
marimo edit notebook.py

​
Supported Formats

marimo can convert from multiple source formats:
Converts Jupyter notebooks to marimo format:
marimo convert analysis.ipynb -o analysis.py
What gets converted:
  • Code cells → marimo cells
  • Markdown cells → mo.md() cells
  • Cell execution order → dependency graph
What gets stripped:
  • All cell outputs (regenerated when you run the notebook)
  • Jupyter metadata
  • Execution counts
Converts markdown files with Python code fences:
marimo convert document.md -o notebook.py
Requirements:
  • Code blocks must use {python} fence notation:
# Analysis

```{python}
import pandas as pd
df = pd.read_csv("data.csv")
```

```{python}
df.head()
```
Converts Python scripts to marimo notebooks:
marimo convert script.py -o notebook.py
Supported formats:
  • py:percent format (VSCode/PyCharm style):
# %%
import pandas as pd

# %%
df = pd.read_csv("data.csv")

# %%
df.head()
  • Plain scripts: marimo attempts intelligent conversion
Requires jupytext for script conversion:
pip install jupytext
marimo convert script.py -o notebook.py

​
Conversion Process

1

Identify the format

marimo detects the file type by extension:
  • .ipynb → Jupyter notebook
  • .md or .qmd → Markdown document
  • .py → Python script
2

Parse the content

Extract code cells, markdown, and dependencies:
  • Jupyter: Reads notebook JSON structure
  • Markdown: Parses {python} code fences
  • Scripts: Identifies cell boundaries (requires jupytext)
3

Build dependency graph

marimo analyzes variable usage to create the reactive graph:
# Cell 1 defines x
x = 10

# Cell 2 uses x → depends on Cell 1
y = x * 2

# Cell 3 uses y → depends on Cell 2
print(y)
4

Generate marimo notebook

Creates a .py file with marimo’s structure:
import marimo

app = marimo.App()

@app.cell
def __():
    x = 10
    return (x,)

@app.cell
def __(x):
    y = x * 2
    return (y,)

​
What Gets Converted

​
Code Cells ✓

Jupyter code cells become marimo cells: 
# Cell 1
import pandas as pd
df = pd.read_csv("data.csv")

# Cell 2
df.describe()

​
Markdown Cells ✓

Markdown becomes mo.md() calls: 
# Data Analysis

This notebook analyzes **sales data**.

​
Cell Outputs ✗

Outputs are NOT preserved:
  • Plots, tables, and text outputs are stripped
  • Re-run the notebook to regenerate outputs
  • This ensures fresh, reproducible results
marimo’s reactivity means outputs update automatically as you edit - no need to manually re-run cells!

​
Manual Adjustments

After conversion, you may need to refactor code that doesn’t fit marimo’s reactive model.

​
Variable Mutations

marimo doesn’t allow multiple cells to define the same variable.
# Cell 1
df = pd.read_csv("data.csv")

# Cell 2
df = df[df['age'] > 18]  # ❌ Redefining df

# Cell 3
df = df.dropna()  # ❌ Redefining df again

​
Side Effects

Minimize global state and side effects: 
# Cell 1
results = []

# Cell 2
results.append(calculate_a())  # ❌ Mutating global

# Cell 3
results.append(calculate_b())  # ❌ Mutating global

​
Display Order

Jupyter executes top-to-bottom; marimo executes by dependency: 
# Cell 1
x = 10

# Cell 2 (must run after Cell 1)
y = x + 5

# Cell 3 (must run after Cell 2)
print(y)

​
Common Issues

Problem: Converting Python scripts fails with missing jupytext.Solution:
pip install jupytext
marimo convert script.py -o notebook.py
Problem: Cells redefine the same variable.Solution: Refactor to define each variable in only one cell:
# Instead of modifying df multiple times,
# create a single transformation pipeline
df_clean = (
    df
    .filter(...)
    .transform(...)
    .dropna()
)
Problem: File has syntax errors.Solution: Fix syntax errors in the original file before conversion:
# Check syntax
python -m py_compile notebook.ipynb
Problem: File is already in marimo format.Solution: No conversion needed! Just open it:
marimo edit notebook.py

​
Conversion Checklist

After converting, verify these items:
  • All cells execute without errors
  • No multiple definitions of the same variable
  • Dependencies are correctly detected
  • Markdown cells render properly
  • Imports are in the first cell
  • No hidden state or global mutations
  • Outputs regenerate correctly

​
Remote Notebooks

Convert notebooks hosted on GitHub: 
# Convert from URL
marimo convert https://github.com/user/repo/blob/main/notebook.ipynb -o local.py

# Then edit
marimo edit local.py

​
Batch Conversion

Convert multiple notebooks: 
# Convert all notebooks in a directory
for file in notebooks/*.ipynb; do
  marimo convert "$file" -o "marimo/${file%.ipynb}.py"
done

​
Comparing with Jupyter

FeatureJupytermarimo
File formatJSON (.ipynb)Python (.py)
ExecutionManual, top-to-bottomAutomatic, reactive
Hidden statePossiblePrevented
Version controlDifficult (JSON)Easy (Python)
ReproducibilityOrder-dependentGuaranteed
DiffsNoisy JSONClean Python
CollaborationMerge conflictsStandard Git workflow

​
Why Convert?

Better Version Control

Plain Python files are easier to diff, merge, and review.

Reproducibility

marimo’s reactivity eliminates hidden state issues.

Interactivity

Built-in UI elements without writing JavaScript.

Deployment

Run as scripts, apps, or export to multiple formats.

​
Next Steps

Creating Notebooks

Learn marimo’s cell structure

Package Management

Add dependencies to your notebooks

Build docs developers (and LLMs) love

Get started for freeTalk to us