Jupyter notebooks are mostly known for their web-based user interface, such as JupyterLab or the Classic Notebook. They offer a great user experience, allow for rich output rendering, provide interactivity through e.g. widgets, and make possible working with remote kernels.

If just like me you tend to never leave the terminal in your workflow, you may be missing a tool to interact with Jupyter notebooks without switching to a web browser. While the Jupyter Console already allows you to interact with a Jupyter kernel in the terminal, it is more comparable to a shell than a notebook.

The notebook differs from the console in that it’s bound to a document, interleaving rich text and executable code. This makes the code representation more structured, while allowing for interactivity. Well, until recently this wasn’t possible in the terminal. But today, we are proud to announce nbterm!

Getting started with nbterm

Launching a notebook is as easy as entering:

$ nbterm my_notebook.ipynb

You can also create a new one if you don’t pass a notebook argument. Almost immediately, you will get a full-screen application that looks like this:

nbterm has other command line options:

$ nbterm --help
Usage: nbterm [OPTIONS] [NOTEBOOK_PATH]

Arguments:
  [NOTEBOOK_PATH]  Path to the notebook.  [default: ]

Options:
  --no-kernel                     Don't launch a kernel.
  --run                           Run the notebook.
  --save-path TEXT                Path to save the notebook.
  --version                       Show the version and exit.
  --help                          Show this message and exit.

For example, it is possible to run all cells of a notebook in batch mode, using:

$ nbterm --run my_notebook.ipynb

If you didn’t specify a new name with --save-path, a new notebook named my_notebook_run.ipynb will be created, with all cell outputs populated. This mode of execution is similar to the nbclient library, but accessible in the command line.

Embedding nbterm

It is also possible to use it as a library and embed it in your own application. Besides, all user interactions can be scripted. For instance, you can rearrange the cells and then run all cells like this:

import asyncio
from nbterm import Notebooknb = Notebook("my_notebook.ipynb")
nb.cut_cell(3)
nb.paste_cell(1)
asyncio.run(nb.run_all())
nb.save()

A lightweight Jupyter stack

While you probably can’t tell the difference, nbterm doesn’t reuse the base Jupyter components such as jupyter-client and nbformat (respectively implementing the Jupyter kernel protocol and the Jupyter Notebook format). The reason is that nbterm was started as a toy project to see how hard it would be to have a minimalist notebook client.

As a Jupyter contributor, I am mostly involved in the maintenance and modernization of these packages. I wanted to experiment with a new project without the backward-compatibility constraints. This resulted in a rather lean code base, and its simplicity makes it suitable to serve as a reference for other language implementations.

The roadmap

While nbterm is obviously more limited than the Notebook, there are several potential improvement directions. Having rich(er) outputs is one of them. The terminal is pretty much limited to showing characters, but people have done great things with ASCII art. An attempt has been made a while ago with an ASCII back-end for matplotlib. And although it’s only on macOS for now, some terminals are capable of showing real pictures, and there exists a Matplotlib back-end for iTerm2.

Another nice feature would be to add some interactivity. In the Notebook, this is typically achieved using widgets, but they are inherently web-based, so this is not an option. Maybe we could imagine something similar to ipywidgets for the terminal, and have simple things like sliders, buttons, menus and such. I am keeping an eye on the awesome Rich library, with which you can already create dashboards, and GUI applications in the future.

Try it!

nbterm really has the look and feel of the Notebook you already know and love, with (almost) the same key bindings, so you won’t be lost. As coders, we love the terminal, and libraries like prompt-toolkit and Rich in Python, or cpp-terminal in C++, make it possible to build beautiful applications. You can install nbterm today using your favorite package manager:

$ pip install nbterm

$ mamba install nbterm -c conda-forge

Be sure to update frequently, as it is improving every day. And if you want to contribute, please get in touch on the GitHub repository.

Acknowledgements

The development of nbterm is sponsored by QuantStack.

About the author

David Brochart is a scientific software developer at QuantStack. He is a contributor to several libraries in the Jupyter ecosystem, such as nbclient, jupyter-client, jupyter-server, ipykernel, and ipywidgets.