jupytext
Convert Jupyter Notebooks to text-based formats
TLDR
Turn a notebook into a paired .ipynb/.py notebook
Convert a notebook to a .py file
Convert a .py file to a notebook with no outputs
Convert a .md file to a notebook and run it
Update the input cells in a notebook and preserve outputs and metadata
Update all paired representations of a notebook
SYNOPSIS
jupytext [OPTIONS]
jupytext --to
jupytext --sync [OPTIONS]
PARAMETERS
--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.
DESCRIPTION
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.
CAVEATS
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.
PAIRED NOTEBOOKS
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.
CONFIGURATION
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.
HISTORY
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.