Skip to main content

​
marimo convert

Convert Jupyter notebooks, Markdown files, or Python scripts to marimo notebook format.

​
Usage

marimo convert FILENAME [OPTIONS]

​
Arguments

FILENAME - File to convert (required)
  • Supported formats: .ipynb, .md, .qmd, .py
  • Can be a local file path
  • Can be a GitHub URL to a notebook

​
Options

-o, —output PATH - Output file path
  • Type: Path
  • If not provided, the converted notebook is printed to stdout
  • Parent directories will be created if they don’t exist

​
Supported Formats

​
Jupyter Notebooks (.ipynb)

  • Converts Jupyter notebooks to marimo format
  • Cell outputs are stripped during conversion
  • Cell execution order is preserved
  • Markdown cells are converted to marimo markdown cells

​
Markdown Files (.md, .qmd)

  • Only {python} fenced code blocks are converted to cells
  • Other content is ignored
  • Example of supported syntax:
```{python}
import pandas as pd
df = pd.DataFrame({'a': [1, 2, 3]})
```

Some text here.

```{python}
print(df)
```

​
Python Scripts (.py)

  • If already a valid marimo notebook: No conversion is performed
  • Otherwise: Attempts conversion using py:percent format
  • Preserves top-level comments and docstrings
  • Supports # %% cell delimiters
Example py:percent format: 
# %% [markdown]
# # My Analysis

# %%
import pandas as pd
import matplotlib.pyplot as plt

# %%
data = pd.read_csv('data.csv')
data.head()

​
Examples

​
Convert Jupyter Notebook

# Convert and save to file
marimo convert notebook.ipynb -o notebook.py

# Convert and print to stdout
marimo convert notebook.ipynb

# Pipe output to another command
marimo convert notebook.ipynb | grep "import"

​
Convert from GitHub

# Convert a notebook from GitHub
marimo convert https://raw.githubusercontent.com/user/repo/main/notebook.ipynb -o notebook.py

​
Convert Markdown

# Convert Markdown document
marimo convert analysis.md -o analysis.py

# Convert Quarto document
marimo convert report.qmd -o report.py

​
Convert Python Script

# Convert py:percent script
marimo convert script.py -o notebook.py

# Check if file is already a marimo notebook
marimo convert my_notebook.py
# Output: "File is already a valid marimo notebook."

​
Using Global Flags

# Suppress output during conversion
marimo -q convert notebook.ipynb -o notebook.py

# Auto-accept prompts (non-interactive)
marimo -y convert notebook.ipynb -o notebook.py

# Combine flags
marimo -q -y convert notebook.ipynb -o notebook.py

​
Workflow Example

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

# Edit the converted notebook
marimo edit notebook.py

​
Important Notes

​
Reactivity Considerations

marimo’s reactive execution model differs from Jupyter’s linear execution:
  • Variables are immutable: Each cell defines variables only once
  • No mutation across cells: Code that modifies variables across multiple cells will need refactoring
Example that needs refactoring: 
# Cell 1 (Jupyter)
df = pd.DataFrame({'a': [1, 2, 3]})

# Cell 2 (Jupyter)
df['b'] = df['a'] * 2  # This mutates df from Cell 1
In marimo, refactor to: 
# Cell 1
df_original = pd.DataFrame({'a': [1, 2, 3]})

# Cell 2
df = df_original.assign(b=lambda x: x['a'] * 2)

​
After Conversion

  1. Review the converted notebook for any issues
  2. Refactor code that mutates variables across cells
  3. Test the notebook to ensure it works as expected
  4. Enjoy marimo’s reactive features!

​
Dependencies

​
For Python Script Conversion

Converting py:percent format Python scripts requires jupytext: 
pip install jupytext
If jupytext is not installed, marimo will provide installation instructions.

​
Error Handling

​
Syntax Errors

If the input file has syntax errors: 
marimo convert broken.py -o notebook.py
# Output: "File cannot be converted. It may have syntax errors."

​
Invalid File Type

marimo convert document.txt -o notebook.py
# Error: File must be an .ipynb, .md, or .py file

​
Already a marimo Notebook

marimo convert existing.py -o output.py
# Output: "File is already a valid marimo notebook."

​
Tips

  • Always review converted notebooks for potential issues
  • Use -o to save the output, or pipe to inspect the conversion
  • For large Jupyter notebooks, consider splitting into smaller marimo notebooks
  • Test converted notebooks thoroughly, especially if they have complex dependencies

Build docs developers (and LLMs) love

Get started for freeTalk to us