“jupytext” is a tool that allows you to convert Jupyter notebooks to plain text documents, such as Python scripts or Markdown files, and vice versa. It provides a convenient way to work with Jupyter notebooks in different formats and collaborate with others who may not have Jupyter installed. This article will walk you through several use cases of the “jupytext” command along with examples.

Use case 1: Turn a notebook into a paired .ipynb/.py notebook

Code:

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

Motivation: This use case is useful when you want to work with both Jupyter notebooks and Python scripts interchangeably. By converting a notebook into a paired .ipynb/.py notebook, you can edit the notebook in Jupyter and the corresponding script in your favorite IDE, ensuring consistency between both representations.

Explanation: The --set-formats option specifies the desired formats for the paired representations of the notebook. In this case, ipynb,py instructs “jupytext” to create both .ipynb and .py versions of the notebook.

Example output: After running the command, you will find two new files: notebook.ipynb and notebook.py, which contain the same content.

Use case 2: Convert a notebook to a .py file

Code:

jupytext --to py notebook.ipynb

Motivation: Converting a notebook to a .py file enables you to share your code with others who may prefer working with traditional Python scripts or execute the code in a non-Jupyter environment. It also allows you to use version control systems more efficiently for your projects.

Explanation: The --to py option specifies the target format for the conversion, telling “jupytext” to convert the notebook.ipynb to a Python script.

Example output: The command will create a notebook.py file that contains the Python code extracted from the notebook.

Use case 3: Convert a .py file to a notebook with no outputs

Code:

jupytext --to notebook notebook.py

Motivation: This use case is helpful when you have a Python script and want to convert it back to a notebook for further analysis, documentation, or interactive exploration. By excluding the outputs, you can focus on the code and observations without the distractions of previous execution results.

Explanation: The --to notebook option instructs “jupytext” to convert the notebook.py file to a Jupyter notebook. Excluding the outputs is the default behavior of “jupytext” for conversion commands.

Example output: The command will generate a notebook.ipynb file containing the code extracted from notebook.py, with no cell outputs.

Use case 4: Convert a .md file to a notebook and run it

Code:

jupytext --to notebook --execute notebook.md

Motivation: Sometimes, you may have Markdown documents containing code snippets that you want to execute and analyze interactively. By converting a .md file to a Jupyter notebook and running it, you can benefit from Jupyter’s interactivity and visualizations.

Explanation: The --to notebook option specifies the target format for the conversion, telling “jupytext” to create a Jupyter notebook. The --execute flag indicates that the newly generated notebook should be executed, making the code snippets in the Markdown file runnable.

Example output: The command will create a notebook.ipynb file containing code cells extracted from notebook.md and their corresponding outputs after executing them.

Use case 5: Update the input cells in a notebook and preserve outputs and metadata

Code:

jupytext --update --to notebook notebook.py

Motivation: When sharing your notebooks with collaborators or working on them across different environments, updating the code cells while preserving the outputs and metadata is essential. This use case allows you to modify the input code while retaining the results and additional information stored in the outputs.

Explanation: The --update option tells “jupytext” to update the input cells in the notebook while preserving the existing outputs and metadata. The --to notebook option specifies the target format as a Jupyter notebook.

Example output: The command will modify the code cells in notebook.py and preserve the outputs and metadata. The resulting notebook.ipynb file will contain the updated code cells with the original outputs intact.

Use case 6: Update all paired representations of a notebook

Code:

jupytext --sync notebook.ipynb

Motivation: In a collaborative environment, different people may work on the same notebook using different representations, such as .ipynb or .py files. This use case allows you to synchronize the changes made in one representation to all other paired representations, maintaining consistency and avoiding conflicts.

Explanation: The --sync option instructs “jupytext” to update all paired representations of the notebook referenced in the command. For example, running the command on notebook.ipynb will update the corresponding notebook.py file, or vice versa.

Example output: After executing the command, the differences in the paired representations of notebook.ipynb will be synchronized, ensuring that both versions have the same content.

Conclusion

“jupytext” is a powerful command-line tool that simplifies working with Jupyter notebooks in various formats. Whether you want to convert notebooks to scripts, update input cells while preserving outputs, or synchronize changes between different representations, “jupytext” provides a flexible and customizable solution. By leveraging “jupytext,” you can enhance collaboration, version control, and reproducibility in your Jupyter-based projects.