nbpreview 0.10.0

nbpreview

nbpreview

A terminal viewer for Jupyter notebooks. It's like cat for ipynb files.

Documentation

nbpreview's documentation contains a detailed breakdown of its features, command-line usage, and instructions on how to configure the tool.

Quick look

Want to just see how nbpreview would render an output on your terminal? Use uv to get a preview. The snippet below installs uv (if not already in your system) and uses it to render a notebook stored in this repository.

% curl -LsSf https://astral.sh/uv/install.sh | sh
% curl https://raw.githubusercontent.com/paw-lu/nbpreview/refs/heads/main/docs/example_notebook_cells/hero_notebook.ipynb | uvx nbpreview

Installation

nbpreview can be installed through any of the major python package managers (eg uv, pipx, or pip from PyPI).

uv is the easiest way to get started, there are multiple ways to install it. (Such as the example snippet above using curl).

% uv tool install nbpreview

nbpreview may also be installed via pip if you prefer:

% python -m pip install nbpreview

Features

Syntax highlight code cells

Render markdown

Draw images

Render DataFrame

Create previews for Vega charts

Render LaTeX

Parse HTML

Create hyperlinks for complex content

Render stderr output

Render tracebacks

Use Nerd Font icons

Try it out

Assuming curl and pipx are installed, nbpreview may be tried out on the terminal by running:

% curl https://raw.githubusercontent.com/paw-lu/nbpreview/main/docs/example_notebook_cells/hero_notebook.ipynb | pipx run nbpreview

Usage

To use nbpreview, type nbpreview into your terminal followed by the path of the notebook you wish to view.

% nbpreview notebook.ipynb

See the command-line reference for details on options.

Contributing

Contributions are very welcome. To learn more, see the contributor guide.

License

Distributed under the terms of the MIT license, nbpreview is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Prior art

Similar tools

Thanks to @joouha for maintaining a list of these tools. Many of the projects here were found directly on their page.

• ipynb-term
• ipynbat
• ipynbviewer
• jcat
• jupview
• jupytui
• jut
• nbcat
• nbtui
• nbv
• Read-Jupyter-Notebook

Complimentary tools

If you're interested in complimentary tools that help improve the terminal experience for notebooks, there are many amazing projects out there.

• bat is not a tool for notebooks specifically. But similar to nbpreview, it provides a rich output for many types of files on the terminal, and is the primary inspiration for nbpreview.
• euporie is a really exciting project that allows you to edit and run Jupyter notebooks on the terminal.
• nbclient is a library for executing notebooks from the command line.
• nbpreview is another project that coincidentally shares a name with this one. It allows for Jupyter notebooks to be rendered without running a notebook server.
• nbqa allows the use of linters and formatters on notebooks. It's also used by this project.
• jpterm is and up-and-coming successor to nbterm which will be accompanied by a web client. Looking forward to seeing this develop.
• nbtermix is an actively-developed fork of nbterm.
• nbterm lets you edit and execute Jupyter Notebooks on the terminal.
• papermill allows the parameterization and execution of Jupyter Notebooks.

Credits

nbpreview relies on a lot of fantastic projects. Check out the dependencies for a complete list of libraries that are leveraged.

Besides the direct dependencies, there are some other projects that directly enabled the development of nbpreview.

• bat is not explicitly used in this project, but served as the primary inspiration. This projects strives to be bat—but for notebooks. Many of nbpreview's features and command-line options are directly adopted from bat.
• Hypermodern Python Cookiecutter is the template this project was generated on. It is a fantastic project that integrates Poetry, Nox, and pre-commit. It's responsible for most of this project's CI.
• justcharts is directly used by this project to generate the Vega and Vega-Lite charts.