jupytext

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

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

$ jupytext --to py [notebook.ipynb]

$ jupytext --to notebook [notebook.py]

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

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

$ jupytext --sync [notebook.ipynb]

jupytext [OPTIONS] ...
jupytext --to [OPTIONS] ...
jupytext --sync [OPTIONS] ...

--to
    Convert the input notebook to the specified text format (e.g., py, md, myst, ipynb).

--from
    Interpret the input file as the specified format before converting or syncing. Useful when processing non-.ipynb files.

--sync
    Synchronize the input notebook (.ipynb) with its paired text representation (e.g., .py or .md). Changes in one are propagated to the other.

--output
    Write the output to a specific file instead of using the default naming convention.

--overwrite
    Overwrite existing output files without prompting.

--set-formats
    Set the output formats for a notebook. Example: ipynb,py:percent.

--set-metadata
    Set specific notebook or cell metadata (e.g., '{"jupytext":{"formats":"ipynb,py:percent"}}').

--execute
    Execute the notebook after conversion. This is similar to nbconvert --execute.

--diff
    Show differences between a notebook and its paired text file, or between two notebooks.

--check
    Check if the notebook and its text representation are identical, returning a non-zero exit code if they differ.

--version
    Show the version number of jupytext.

--help
    Display a help message and exit.

jupytext is a command-line tool that enables two-way conversion between Jupyter notebooks (.ipynb files) and various plain text formats, including Python scripts (.py), Markdown documents (.md), MyST Markdown (.myst), R scripts (.R), and Julia scripts (.jl). Its primary purpose is to make Jupyter notebooks more version control friendly. By representing notebooks as plain text, it becomes significantly easier to track changes, perform diffs, and merge conflicts using standard Git tools. jupytext allows users to edit the text representation of a notebook (e.g., a .py file with code cells and markdown comments) and then convert it back to an .ipynb file, preserving cell outputs and metadata. It also supports synchronization, keeping both the .ipynb and its text representation in sync. This facilitates collaborative development and integration of notebooks into traditional software development workflows.

While jupytext excels at managing notebook source, some aspects like rich cell outputs (e.g., plots, interactive widgets) are inherently difficult to represent in plain text and are typically stored only in the .ipynb file. When converting from .ipynb to a text format, cell outputs are generally stripped to keep the text file clean and diffable. Also, notebook-level metadata can be complex; ensure proper configuration (e.g., via jupytext.toml or embedded in the text file) to avoid unintended changes or loss of information when round-tripping. For complete execution and rich output handling, the original .ipynb file is usually required.

One of jupytext's most powerful features is the concept of paired notebooks. This allows you to maintain both an .ipynb file and a plain text representation (e.g., a .py script or .md file) of the same notebook side-by-side. When you modify one, jupytext can synchronize the changes to the other using the --sync option. This enables editing the notebook in a text editor for easier code review and diffing, while still having the fully executable .ipynb with outputs available for interactive use or sharing.

jupytext can be configured globally via Jupyter's configuration files (e.g., ~/.jupyter/jupyter_notebook_config.py or ~/.jupyter/jupyter_server_config.py), or locally per project using a jupytext.toml file. These configurations can specify default pairing formats, metadata filters, and other behaviors, making it easier to enforce consistent workflows across projects or teams without manually setting options for every conversion.

jupytext was created by Marc Wouts to address a fundamental challenge with Jupyter notebooks: their native .ipynb format, being a JSON file, makes them difficult to manage effectively with traditional version control systems like Git. The tool's development aimed to provide a robust solution for tracking changes, reviewing code, and merging contributions in a more granular and human-readable way. Since its initial release, jupytext has gained significant traction within the data science and software development communities as a key component for enabling Git-friendly workflows for Jupyter notebooks, becoming a standard practice for many collaborative projects.

jupyter(1), nbconvert(1), git(1)