Skip to content
Jupytext Jupytext

Introduction

Have you always wished Jupyter notebooks were plain text documents? Wished you could edit them in your favorite IDE? And get clear, meaningful diffs when doing version control? Then Jupytext may well be the tool you’re looking for!

Jupytext can save Jupyter notebooks as text files — for instance with a .py or .md extension — and open them again as notebooks. A text notebook contains only your inputs (and selected metadata), so it is:

  • easy to version control — clean, line-by-line diffs instead of unreadable JSON;
  • easy to edit — open and refactor it in VS Code, PyCharm, Spyder, vim, or any editor;
  • easy to share and reuse — a Python text notebook is also an importable module or a script;
  • easy for AI assistants — tools like Claude, GitHub Copilot and Cursor read and edit plain text directly, so they can refactor your notebooks with no JSON wrangling.

How it works

Section titled “How it works”

You have two complementary ways to use Jupytext.

Text notebooks

Section titled “Text notebooks”

A text notebook is a script or Markdown document that you open and run as a notebook. It contains the inputs only — no outputs — which makes it perfect for version control. This is the lightest setup: a single text file is your notebook.

Paired notebooks

Section titled “Paired notebooks”

A paired notebook is a pair of files — a classic .ipynb (which keeps your rich outputs) plus a text file like .py or .md (which is clean and reviewable). Jupytext keeps the two in sync every time you save. You commit the text file, and your outputs stay safe in the .ipynb.

A 60-second tour

Section titled “A 60-second tour”

Install Jupytext:

Terminal window
pip install jupytext

Convert a notebook to a text file (and back):

Terminal window
jupytext --to py:percent notebook.ipynb   # notebook.ipynb -> notebook.py
jupytext --to notebook notebook.py        # notebook.py    -> notebook.ipynb

Pair a notebook so both representations stay in sync on every save:

Terminal window
jupytext --set-formats ipynb,py:percent notebook.ipynb

Or pair every notebook in your project by adding a jupytext.toml file:

formats = "ipynb,py:percent"

Where to next

Section titled “Where to next”