jupytext

library1.19.5pypypi✓ verified 24d ago

Jupytext is a Jupyter plugin that allows users to save Jupyter notebooks as various plain text formats, including Markdown documents, Julia, Python, or R scripts. This enables easier version control with tools like Git and allows editing notebooks in standard IDEs. It supports two-way synchronization between the `.ipynb` file and its paired text representation. The current version is 1.19.1, and the library maintains an active release cadence.

data workflow

pip install jupytext

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · JUPYTEXT

jupytext

datapythonv1.19.5

Install

3.7s avg

Import

760ms

Disk

28MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.19.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.786s · 29.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.7s · import 0.734s · 30MB

28MB installed

● package 28MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

read

✓ from jupytext import read

Used to read a notebook from a text file or .ipynb.

write

✓ from jupytext import write

Used to write a notebook to a text file or .ipynb.

This quickstart demonstrates how to create a basic `.ipynb` file, then use the `jupytext` command-line interface to pair it with a Python script (`.py:percent` format) and synchronize the two. The pairing and synchronization ensure that changes in one file are reflected in the other.

# Create a sample Jupyter notebook file with open('my_notebook.ipynb', 'w') as f: f.write('{\"cells\": [{\"cell_type\": \"code\", \"execution_count\": null, \"metadata\": {}, \"outputs\": [], \"source\": [\"print(\\\"Hello from Jupytext!\\\")\"]}, {\"cell_type\": \"markdown\", \"metadata\": {}, \"source\": [\"# A Markdown Cell\"]}], \"metadata\": {\"kernelspec\": {\"display_name\": \"Python 3\", \"language\": \"python\", \"name\": \"python3\"}}, \"nbformat\": 4, \"nbformat_minor\": 4}') # Pair the .ipynb notebook with a Python script in percent format # and then synchronize them import subprocess print("Pairing notebook.ipynb with notebook.py:percent...") subprocess.run(['jupytext', '--set-formats', 'ipynb,py:percent', 'my_notebook.ipynb'], check=True) print("Synchronizing files...") subprocess.run(['jupytext', '--sync', 'my_notebook.ipynb'], check=True) print("Generated files:") subprocess.run(['ls', 'my_notebook.*']) # Optionally, read the created .py file content with open('my_notebook.py', 'r') as f: print('\n--- my_notebook.py content ---') print(f.read()) # Clean up (optional) # import os # os.remove('my_notebook.ipynb') # os.remove('my_notebook.py')

jupytext --version

Debug

Known issues

breakingJupytext dropped support for Python 3.8 starting with version 1.17.2, as Python 3.8 reached its End-of-Life. Users on older Python versions must upgrade to at least Python 3.9 or use an older Jupytext version.

fix

Upgrade your Python environment to 3.9 or higher.

affects: >=1.17.2

gotchaWhen using `jupytext --sync` as a `pre-commit` hook, it can sometimes introduce unstaged changes or lead to an infinite loop if not configured correctly. The `--pre-commit-mode` flag is crucial to prevent this behavior.

fix

Always use `jupytext --pre-commit-mode` in pre-commit hooks. Ensure that `types_or: [jupyter, python]` and `require_serial: true` are set in your `.pre-commit-config.yaml` for Jupytext hooks.

affects: <=1.19.1

gotchaOlder versions of Jupytext (pre-1.19.0) could produce warnings about missing or unexpected 'id' fields in cells when converting to certain formats like Pandoc. This was a common validation warning.

fix

Upgrade to Jupytext 1.19.0 or later to resolve these cell ID warnings.

affects: <1.19.0

breakingThe behavior of `jupytext --set-formats` changed in version 1.17.2. It no longer overrides existing paired files by default, instead respecting existing pairings. Workflows that relied on `--set-formats` to forcibly overwrite paired files may need adjustment.

fix

Review scripts using `--set-formats`. If overriding existing files is still desired, ensure no conflicting pairing metadata exists or consider a `jupytext --to` command.

affects: >=1.17.2

gotchaAfter installing Jupytext, especially the JupyterLab extension, a full restart/reload of the Jupyter server and/or JupyterLab interface is often required for the extension to be recognized and activated correctly.

fix

Restart your JupyterLab or Jupyter Notebook server after installation (`jupyter lab stop` then `jupyter lab`). If the server extension message `[Jupytext Server Extension] Changing NotebookApp.contents_manager_class` is not seen, enable it explicitly with `jupyter serverextension enable jupytext`.

affects: All

gotchaWhen exporting notebooks to Python scripts (in formats other than `py:percent`) or R Markdown, Jupyter magic commands (`%matplotlib inline`, `%%timeit`) are commented out by default. This is because IDEs do not understand these magics. This behavior can be controlled.

fix

Use the `py:percent` format to preserve magics or set the `comment_magics` option in notebook metadata or Jupyter configuration (`c.ContentsManager.comment_magics = False`).

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'jupytext'

Jupytext is not installed in the Python environment from which Jupyter is launched, or its server extension is not properly enabled.

fix

First, install Jupytext using `pip install jupytext` or `conda install jupytext -c conda-forge`. Then, enable the server extension with `jupyter serverextension enable jupytext --sys-prefix` and restart your Jupyter/JupyterLab server.

Jupyter complains that the .ipynb file is more recent than the text representation.

This warning occurs when the `.ipynb` file and its paired text representation (e.g., `.py` or `.md`) have different timestamps, typically because the text file was edited externally without the `.ipynb` being updated or reloaded in Jupyter.

fix

In Jupyter, click 'Reload' when prompted. If the changes in the text file are desired, save the notebook to synchronize the `.ipynb` file. Alternatively, use the command-line interface `jupytext --sync notebook.ipynb` to force synchronization based on timestamps.

jupytext not syncing notebook to python files

The Jupytext contents manager might not be active, the notebook is not correctly paired, or there's a configuration issue preventing automatic two-way synchronization on save.

fix

Ensure Jupytext is installed and its server extension is enabled (`jupyter serverextension enable jupytext --sys-prefix`). Verify that the notebook is paired using the Jupytext commands in JupyterLab, or by adding a `"jupytext": {"formats": "ipynb,py:percent"}` entry to the notebook's metadata. After pairing, saving the notebook should create/update the paired file.

'jupytext' is not recognized as an internal or external command

The `jupytext` command-line executable is not found in the system's PATH, or the JupyterLab extension for Jupytext is not correctly installed or linked in the active Jupyter environment.

fix

Confirm Jupytext is installed in the correct Python environment (`pip install jupytext` or `conda install jupytext -c conda-forge`). Restart your terminal and Jupyter server. If using JupyterLab, also check `jupyter labextension list` to ensure the `jupyterlab-jupytext` extension is enabled.

Upgrade

Version history

1.19.5latest on PyPI · released Jul 21, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mwouts/jupytext ↗

packagehttps://pypi.org/project/jupytext/ ↗

homepagehttps://jupytext.readthedocs.io ↗

docshttps://jupytext.readthedocs.io ↗