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.
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.
Jupytext can also convert these formats into Jupyter Notebooks, allowing for two-directional syncing between formats. See below for a quick demo.
How to use Jupytext¶
There are multiple ways to use
- Directly from Jupyter Notebook or JupyterLab. Jupytext provides a contents manager that allows Jupyter to save your notebook to your favorite format (
.Rmd…) in addition to (or in place of) the traditional
.ipynbfile. The text representation can be edited in your favorite editor. When you’re done, refresh the notebook in Jupyter: inputs cells are loaded from the text file, while output cells are reloaded from the
.ipynbfile if present. Refreshing preserves kernel variables, so you can resume your work in the notebook and run the modified cells without having to rerun the notebook in full.
- On the command line.
jupytextconverts Jupyter notebooks to their text representation, and back. The command line tool can act on notebooks in many ways. It can synchronize multiple representations of a notebook, pipe a notebook into a reformatting tool like
black, etc… It can also work as a pre-commit hook if you wish to automatically update the text representation when you commit the
- in Vim: edit your Jupyter notebooks, represented as a Markdown document, or a Python script, with jupytext.vim.
Jupytext implements a series of text formats for notebooks, which are documented here.
In short: the Markdown representation of notebooks fits well the notebooks that contain narratives, while notebooks that mostly contain code are conveniently saved as scripts. The most popular formats for notebooks as scripts are:
percentformat (in which cells are delimited with
# %%) also used by Spyder, VSCode, PyCharm, and others,
- and the
lightformat which was developed to support this project.
lightuses as few cell markers as possible and is particularly suited for importing a pre-existing python script as a notebook with cell divisions automatically inferred from paragraph breaks in the source code.
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)
- See how you can edit Jupyter Notebooks in VS Code or PyCharm with (or without!) Jupytext (Jan. 2020)
- or, try Jupytext online with binder!