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.
In Jupyter Notebook, pair your notebook to one or more text formats with the Jupytext menu:
In JupyterLab, use the Jupytext commands:
These command simply add a "jupytext": {"formats": "ipynb,md"}-like entry in the notebook metadata.
You can also configure the notebook pairing on the command line, and set a default pairing for all the notebooks either globally or in a subfolder - see here.
When saving a paired notebook using Jupytext's contents manager, Jupyter updates both the .ipynb and its text representation. The text representation can be edited outside of Jupyter. When the notebook is refreshed in Jupyter, the input cells are read from the text file, and the output cells from the .ipynb file.
It is possible (and convenient) to leave the notebook open in Jupyter while you edit its text representation. However, you don't want the two editors to save the notebook simultaneously. To avoid this:
- deactivate Jupyter's autosave, by either toggling the
"Autosave notebook"menu entry or run%autosave 0in a cell of the notebook (see in the faq how to deactivate autosave permanently) - and refresh the notebook when you switch back from the editor to Jupyter.
In case you forgot to refresh, and saved the Jupyter notebook while the text representation had changed, no worries: Jupyter will ask you which version you want to keep:
When that occurs, please choose the version in which you made the latest changes. And give a second look to our advice to deactivate the autosaving of notebooks in Jupyter.
With Jupytext's contents manager for Jupyter, scripts and Markdown documents gain a notebook icon. If you don't see the notebook icon, double check the contents manager configuration.
By default, Jupyter Notebook open scripts and Markdown documents as notebooks. If you want to open them with the text editor, select the document and click on edit:
In JupyterLab this is slightly different. Scripts and Markdown document also have a notebook icon. But they open as text by default. Open them as notebooks with the Open With -> Notebook context menu (available in JupyterLab 0.35 and above):
If do not want to classify scripts or Markdown documents as notebooks, please use the notebook_extension option. For instance, if you want to get the notebook icon only for .ipynb and .Rmd files, set
notebook_extensions = "ipynb,Rmd"
in your local or global jupytext.toml file.
Please note that, with the above setting, Jupyter will not let you open scripts as notebooks. If you still want to do so, use the Jupytext command line (see below) to first convert or pair the script to an .ipynb notebook.