jupytext

converts Jupyter notebooks to text formats

TLDR

Convert a notebook to a Python percent script

$ jupytext --to py:percent [notebook.ipynb]

Convert a Python script back to a notebook

$ jupytext --to ipynb [script.py]

Convert a notebook to Markdown and write to a specific output file

$ jupytext --to md --output [output.md] [notebook.ipynb]

Pair a notebook with a Python percent script for version control

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

Sync all paired representations, updating whichever file is outdated

$ jupytext --sync [notebook.ipynb]

Pipe the text representation through black to reformat in place

$ jupytext --pipe black [notebook.ipynb]

Convert a Markdown notebook to ipynb and execute it

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

SYNOPSIS

jupytext [options] notebook [notebook ...]

Jupytext converts Jupyter notebooks to plain-text formats such as Python scripts and Markdown files, and back again. This makes notebooks suitable for version control, code review, and editing in a standard IDE.The most common workflow is to pair a `.ipynb` notebook with a `.py` or `.md` file using `--set-formats`. Once paired, running `--sync` keeps both files up to date: the paired text file captures inputs cleanly for version control, while the `.ipynb` retains cell outputs.The `percent` format (`py:percent`) is the recommended script format. Cells are delimited by `# %%` markers and the files are valid Python. The `light` format uses minimal markers. Markdown-based formats include plain `md`, `md:myst` (MyST Markdown, compatible with Jupyter Book), and `Rmd` (R Markdown).Jupytext integrates with JupyterLab as an extension: text notebooks open with a notebook icon and can be launched directly. It also works with pre-commit hooks for automated formatting.

PARAMETERS

--to FORMAT

Target format. Common values: `py`, `py:percent`, `py:light`, `ipynb`, `md`, `md:myst`, `Rmd`. The part after `:` selects the sub-format.

--from FORMAT

Explicitly specify the source format, required when reading from stdin.

-o FILE, --output FILE

Output file path. Use `-` to write to stdout.

--sync

Sync all paired representations of a notebook based on file timestamps, updating whichever copy is outdated.

--set-formats FORMATS

Pair the notebook with one or more additional formats (e.g. `ipynb,py:percent`). Writes pairing metadata into the notebook.

--update

When converting to an existing `.ipynb` file, preserve existing outputs and metadata and only update the input cells.

--pipe CMD

Pipe the text representation of the notebook through an external command (e.g. `black` or `isort`). Use `{}` as a placeholder for a temporary file when the command does not accept stdin.

--pipe-fmt FORMAT

Format to use when piping (default: `py:percent`).

--check CMD

Run a command on the text representation and fail if it returns a non-zero exit code. Use `{}` as a placeholder for a temporary file.

--execute

Execute the notebook cells after conversion (requires `nbconvert`).

--set-kernel NAME

Set the kernel in the notebook YAML header. Use `-` to use the kernel matching the current Python executable.

--update-metadata JSON

Update notebook-level metadata with the provided JSON string (e.g. `'{"kernelspec":{"name":"python3"}}'`).

--opt KEY=VALUE

Set a jupytext option, such as `comment_magics=false`.

--test

Test that the round-trip conversion (notebook -> text -> notebook) is lossless.

--test-strict

Like `--test`, but performs a strict byte-for-byte comparison of the two notebooks.

--help

Display help information.

CAVEATS

Cell outputs (images, tables, rich output) are not stored in text formats and are lost on conversion unless paired with an `.ipynb` file. The `.ipynb` file must exist or be regenerated by executing the notebook to restore outputs.

HISTORY

Jupytext was created by Marc Wouts to solve version control challenges with Jupyter notebooks. It began as a JupyterLab extension and later added a full command-line interface.