Converting from Jupyter

Migrate Jupyter notebooks to marimo’s reactive format

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:

Jupyter Notebooks (.ipynb)

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

Markdown Files (.md, .qmd)

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()
```

Python Scripts (.py)

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:

Jupyter

# Cell 1
import pandas as pd
df = pd.read_csv("data.csv")

# Cell 2
df.describe()

Markdown Cells ✓

Markdown becomes mo.md() calls:

Jupyter

# 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.

Jupyter (multiple definitions)

# 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:

Avoid - Global mutations

# 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:

Jupyter (execution order matters)

# 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

Import Error: jupytext

Problem: Converting Python scripts fails with missing jupytext.

Solution:

pip install jupytext
marimo convert script.py -o notebook.py

Multiple Definition Error

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()
)

Syntax Errors

Problem: File has syntax errors.

Solution: Fix syntax errors in the original file before conversion:

# Check syntax
python -m py_compile notebook.ipynb

Already a marimo Notebook

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

Feature	Jupyter	marimo
File format	JSON (.ipynb)	Python (.py)
Execution	Manual, top-to-bottom	Automatic, reactive
Hidden state	Possible	Prevented
Version control	Difficult (JSON)	Easy (Python)
Reproducibility	Order-dependent	Guaranteed
Diffs	Noisy JSON	Clean Python
Collaboration	Merge conflicts	Standard 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