jupytext

Turn a notebook into a paired .ipynb/.py notebook

$ jupytext --set-formats ipynb,py [path/to/notebook].ipynb

$ jupytext --to py [path/to/notebook].ipynb

$ jupytext --to notebook [path/to/notebook].py

$ jupytext --to notebook --execute [path/to/notebook].md

$ jupytext --update --to notebook [path/to/notebook].py

$ jupytext [[-s|--sync]] [path/to/notebook].ipynb

jupytext [OPTIONS] [NOTEBOOK_OR_PATH] ...

--to
    Convert input notebook(s) to specified output FORMAT(s), e.g., py, md:myst

--from
    Read input from text FORMAT(s) instead of .ipynb

--set-formats
    Set notebook metadata jupytext.formats to pair with text files, e.g., py:percent,md:myst

--update
    Update jupytext metadata in .ipynb files without conversion

--check
    Check if paired text notebooks are in sync with .ipynb

--sync
    Synchronize paired text representations with .ipynb notebook

--execute
    Execute notebook cells before saving (requires Jupyter)

-p , --opt
    Set execution/test options, e.g., -p kernel_name=python3

--allow-errors
    Continue execution despite errors

--test
    Test notebook execution without saving

--test-cm
    Test notebook with custom code manager

--version
    Show jupytext version

--help
    Show help

Jupytext is a command-line tool and Python library that enables bidirectional conversion between Jupyter notebooks (.ipynb files) and plain text formats like Markdown, Python scripts, R scripts, or Julia scripts. This facilitates better version control with Git, easier editing in text editors, and improved collaboration.

It pairs notebooks with text representations via notebook metadata (jupytext.formats), allowing automatic synchronization. Edit the text file, run jupytext --sync, and the .ipynb updates. Supported formats include py:percent (Python with %% cells), py:light, md:myst (MyST Markdown), md, and more.

Key features: lossless round-trip conversion preserving outputs/metadata; execution of text notebooks via --execute; checking sync with --check; customizable via CLI options or config files. Ideal for reproducible research, CI/CD pipelines, and avoiding binary .ipynb diffs in Git.

Requires Python 3.6+ and Jupyter; installed via pip install jupytext. Widely used in data science for literate programming.

Requires Python/Jupyter ecosystem; not lossless for all extensions; Git LFS recommended for large .ipynb; some formats lose cell attachments.

pip install jupytext; optional pip install jupyter for execution features.

py:percent (%% cells), py:light (no markers), md (Pandoc), md:myst (MyST), Rmd, qmd (Quarto), ipynb (passthrough). See jupytext --help-formats.

jupytext --set-formats py:percent notebook.ipynb
jupytext notebook.ipynb --to py
jupytext --check notebook.ipynb

Developed by Marc Wouts starting 2019 as open-source Python project. Reached v1.0 in 2020 with stable pairing/sync. Actively maintained on GitHub; v1.15+ adds MyST/R support. Popular in data science for Git-friendly notebooks.

jupyter(1), nbconvert(1)