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 can save Jupyter notebooks as
- Markdown and R Markdown documents,
- Scripts in many languages.
It can also convert these documents into Jupyter Notebooks, allowing you to synchronize content in both directions.
percentformat, compatible with several IDEs, including Spyder, Hydrogen, VScode and PyCharm. In that format, cells are delimited with a commented
lightformat, designed for this project. Use that format to open standard scripts as notebooks, or to save notebooks as scripts with few cell markers - none when possible.
Looking for a demo?
- Read the original announcement in Towards Data Science (Sept. 2018),
- Watch the PyParis talk (Nov. 2018),
- Read our article on Jupytext and Papermill in CFM Insights (Sept. 2019)
- or, try Jupytext online with binder!
Jupytext is available on pypi and on conda-forge. Run either of
pip install jupytext --upgrade
conda install -c conda-forge jupytext
If you want to use Jupytext within Jupyter Notebook or JupyterLab, make sure you install Jupytext in the Python environment where the Jupyter server runs. If that environment is read-only, for instance if your server is started using JupyterHub, install Jupytext in user mode with:
/path_to_your_jupyter_environment/python -m pip install jupytext --upgrade --user
Jupytext's contents manager
Jupytext provides a contents manager for Jupyter that allows Jupyter to open and save notebooks as text files. When Jupytext's content manager is active in Jupyter, scripts and Markdown documents have a notebook icon.
In most cases, Jupytext's contents manager is activated automatically by Jupytext's server extension. When you restart either
jupyter lab or
jupyter notebook, you should see a line that looks like:
[I 10:28:31.646 LabApp] [Jupytext Server Extension] Changing NotebookApp.contents_manager_class from LargeFileManager to jupytext.TextFileContentsManager
If you don't have the notebook icon on text documents after a fresh restart of your Jupyter server, you can either enable our server extension explicitly (with
jupyter serverextension enable jupytext), or install the contents manager manually. Append
c.NotebookApp.contents_manager_class = "jupytext.TextFileContentsManager"
.jupyter/jupyter_notebook_config.py file (generate a Jupyter config, if you don't have one yet, with
jupyter notebook --generate-config). Our contents manager accepts a few options: default formats, default metadata filter, etc. Then, restart Jupyter Notebook or JupyterLab, either from the JupyterHub interface or from the command line with
jupyter notebook # or lab
Jupytext menu in Jupyter Notebook
Jupytext includes an extensions for Jupyter Notebook that adds a Jupytext section in the File menu.
If the extension was not automatically installed, install and activate it with
jupyter nbextension install --py jupytext [--user] jupyter nbextension enable --py jupytext [--user]
Jupytext commands in JupyterLab
In JupyterLab, Jupytext adds a set of commands to the command palette:
The lab extension is included in the Python package. Unless you need to use an older version of the extension you don't have to either install or update the extension manually from npm.
Installing Jupytext will trigger a build of JupyterLab the next time you open it. If you prefer, you can trigger the build manually with
jupyter lab build
The version of the extension that is shipped with Jupytext requires JupyterLab 1.0. If you prefer to continue using JupyterLab in version 0.35, you should install the version 0.19 of the extension:
jupyter labextension install email@example.com
Paired notebooks in the Jupyter Server
Jupytext can write a given notebook to multiple files. In addition to the original notebook file, Jupytext can save the input cells to a text file — either a script or a Markdown document. Put the text file under version control for a clear commit history. Or refactor the paired script, and reimport the updated input cells by simply refreshing the notebook in Jupyter.
Configuring notebooks to use Jupytext
Alternatively, the pairing information for one or multiple notebooks can be set on the command line:
jupytext --set-formats ipynb,py notebook.ipynb
For more information see the jupytext documentation.
Command line conversion
The package provides a
jupytext script for command line conversion between the various notebook extensions:
jupytext --to py notebook.ipynb # convert notebook.ipynb to a .py file jupytext --to notebook notebook.py # convert notebook.py to an .ipynb file with no outputs jupytext --to notebook --execute notebook.md # convert notebook.md to an .ipynb file and run it jupytext --update --to notebook notebook.py # update the input cells in the .ipynb file and preserve outputs and metadata jupytext --set-formats ipynb,py notebook.ipynb # Turn notebook.ipynb into a paired ipynb/py notebook jupytext --sync notebook.ipynb # Update all paired representations of notebook.ipynb
For more examples, see the jupytext documentation
Want to contribute?
Contributions are welcome. Please let us know how you use
jupytext and how we could improve it. You think the documentation could be improved? Go ahead and edit it on GitHub! Read our
CONTRIBUTING.md to find out guidelines and instructions on how to setup a development environment. And stay tuned for more demos on medium and twitter!