Coming from Jupytext

If you're familiar with Jupytext, you'll find that marimo offers similar functionality for working with notebooks as Python files, but without the need for additional setup or synchronization issues because marimo notebooks are stored as .py files by default. However, Jupytext works with IPython notebooks, whereas marimo works with marimo notebooks, which are not based on IPython/Jupyter. Here's a comparison to help you transition smoothly.

Notebook Format

Jupytext	marimo
Jupytext uses comments or special markers to define cell types in notebooks.	Notebooks are pure Python (.py) files by default, using standard Python syntax, such as decorators and functions, to define cells.

Converting Jupyter notebooks

From .ipynb

Jupytext	marimo
jupytext --to py notebook.ipynb	marimo convert notebook.ipynb > notebook.py

From py:percent notebooks to marimo notebooks

If you have a Python file encoded in the py:percent format, you can convert it to a marimo notebook in two steps:

jupytext --to notebook.ipynb percent_notebook.py
marimo convert notebook.ipynb > marimo_notebook.py

To .ipynb

Jupytext	marimo
jupytext --to notebook.ipynb notebook.py	marimo export ipynb notebook.py > notebook.ipynb

Editing Notebooks

Jupytext	marimo
Requires synchronization between .ipynb and .py files.	Edit marimo notebooks files directly in the marimo editor (marimo edit notebook.py), and changes are read from and written to the same file.

Executing Notebooks

Jupytext	marimo
Use Jupyter to edit notebooks interactively, or Papermill to execute notebooks from the command line.	In addition to running notebooks interactively (marimo notebook.py), you can run notebooks as scripts (python notebook.py) or as apps (marimo run notebook.py), passing values to them with marimo's built-in support for CLI args.

Version Control

Jupytext	marimo
Jupyter notebooks are stored as JSON by default, making them difficult to meaningfully version with git. Use Jupytext to pair and synchronize jupyter notebooks with text representations for smaller git diffs.	Notebooks are already in .py format, making them git-friendly by default. Small changes to the notebook are guaranteed to yield small diffs.

Markdown and Code Cells

Jupytext	marimo
Uses special markers or formats to distinguish cell types. Magical syntax is required.	Uses mo.md("...") for Markdown content, and interpolate Python values with mo.md(f"..."); no magical syntax.

Deployment

Jupytext	marimo
Requires migrating to other libraries like Voila or Streamlit for deployment.	Can be deployed as interactive web apps with marimo run.