Need help with jupytext?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

mwouts
4.9K Stars 307 Forks MIT License 2.2K Commits 74 Opened issues

Description

Jupyter Notebooks as Markdown Documents, Julia, Python or R scripts

Services available

!
?

Need anything else?

Contributors list

# 9,079
knitr
jupyter...
Jupyter...
q
1957 commits
# 55,505
Markdow...
knitr
q
nbconve...
54 commits
# 7,144
jupyter
scikit-...
The Jul...
sphinx-...
10 commits
# 92,228
Arch Li...
Apache ...
scalajs
knitr
6 commits
# 110,588
knitr
Jupyter...
q
jupyter
5 commits
# 34,275
jarvis
Google
q
magnum
5 commits
# 4,326
jupyter
jupyter...
mathema...
html5
4 commits
# 22,573
python-...
q
denoisi...
gtk
3 commits
# 28,721
q
vim-mod...
declara...
pandas
3 commits
# 141,661
Shell
knitr
Jupyter...
q
3 commits
# 56,259
openapi
swagger
visual-...
q
2 commits
# 201,488
sed
cpython
cython
knitr
2 commits
# 309,287
Shell
knitr
rstudio
Jupyter...
2 commits
# 285,118
Shell
knitr
Jupyter...
q
2 commits
# 143,638
Shell
knitr
Jupyter...
q
2 commits
# 30,921
jupyter...
jupyter
knitr
q
2 commits
# 298,482
Jupyter...
Shell
knitr
rstudio
2 commits
# 309,329
Shell
knitr
rstudio
Jupyter...
2 commits
# 373,584
Shell
jupyter...
knitr
Jupyter...
1 commit
# 11,314
q
pandas
scikit-...
backtes...
1 commit

CI Documentation Status codecov.io Language grade: Python Code style: black GitHub language count Conda Version Pypi pyversions Binder:notebook Binder:lab

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

Jupytext is a plugin for Jupyter that can save Jupyter notebooks as either - Markdown files (or MyST Markdown files, or R Markdown or Quarto text notebooks) - Scripts in many languages.

Use cases

Common use cases for Jupytext are: - Doing version control on Jupyter Notebooks - Editing, merging or refactoring notebooks in your favorite text editor - Applying Q&A checks on notebooks.

Install

You can install Jupytext with -

pip install jupytext
- or
conda install jupytext -c conda-forge
.

Please note that Jupytext includes an extension for Jupyter Lab. In the latest version of Jupytext, this extension is compatible with Jupyter Lab >= 3.0 only. If you use Jupyter Lab 2.x, please either stay with Jupytext 1.8.2, or install, on top of the latest pip or conda version of Jupytext, a version of the extension that is compatible with Jupyter Lab 2.x:

jupyter labextension install [email protected]  # For Jupyter Lab 2.x

Then, restart your Jupyter server (for more installation details, see the install section in the documentation).

When Jupytext is installed,

.py
and
.md
files have a notebook icon. And you can really open and run these files as notebooks
    With a click on the text file in Jupyter Notebook

    (click on the image above to try this on Binder)

    With a right click and open with notebook in Jupyter Lab

    (click on the image above to try this on Binder)

Paired notebooks

The most convenient way to use Jupytext is probably through paired notebooks.

To pair a given

.ipynb
or text notebook to an additional notebook format, use either
    the "pair notebook with..." commands in Jupyter Lab

    the "pair notebook with..." menu entries in Jupyter Notebook

    jupytext at the command line

    with e.g.

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

    see the documentation.

    or a local or global jupytext.toml configuration file.

    with e.g. the following content:

    formats = "ipynb,py:percent"

    see the documentation.

When you save a paired notebook in Jupyter, both the

.ipynb
file and the text version are updated on disk.

When a paired notebook is opened or reloaded in Jupyter, the input cells are loaded from the text file, and combined with the output cells from the

.ipynb
file.

You can edit the text representation of the notebook in your favorite editor, and get the changes back in Jupyter by simply reloading the notebook (Ctrl+R in Jupyter Notebook, "reload notebook" in Jupyter Lab). And the changes are propagated to the

.ipynb
file when you save the notebook.

Alternatively, you can synchronise the two representations by running

jupytext --sync notebook.ipynb
at the command line.

Which text format?

Jupytext implements many text formats for Jupyter Notebooks. If your notebook is mostly made of code, you will probably prefer to save it as a script: - Use the percent format, a format with explicit cell delimiters (

# %%
), supported by many IDE (Spyder, Hydrogen, VS Code, PyCharm and PTVS) - Or use the light format, if you prefer to see fewer cell markers.

If your notebook contains more text than code, if you are writing a documentation or a book, you probably want to save your notebook as a Markdown document - Use the Jupytext Markdown format if you wish to render your notebook as a

.md
file (without its outputs) on GitHub - Use the MyST Markdown format, a markdown flavor that “implements the best parts of reStructuredText”, if you wish to render your notebooks using Sphinx or Jupyter Book. - Use the R Markdown format or the Quarto format if you want to open your Jupyter Notebooks in RStudio.

More resources?

If you're new to Jupytext, you may want to start with the FAQ or with the Tutorials, or with this short introduction to Jupytext: .

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.