Skip to main content


Project description

nbpreview light logo nbpreview dark logo


Checked with mypy PyPI Status Python Version License Read the documentation at Tests Codecov pre-commit Black Imports: isort security: bandit

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

Hero image


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


  • Python 3.8+


nbpreview can be installed through pipx or pip from PyPI.

pipx provides an easy way to install Python applications in isolated environments. See the documentation for how to install pipx.

% pipx install nbpreview

If pipx is not installed, nbpreview may also be installed via pip:

% python -m pip install nbpreview


Syntax highlight code cells

Material theme syntax highlighting

Render markdown

Markdown render

Draw images

Block drawing of image

Render DataFrame

DataFrame render

Create previews for Vega charts

DataFrame render

Render LaTeX

LaTeX render

Parse HTML

HTML render

Create hyperlinks for complex content

Hyperlink renders

Render stderr output

Stderr render

Render tracebacks

Traceback render

Use Nerd Font icons

Try it out

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

% curl | pipx run nbpreview


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.


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


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


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.

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.


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.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nbpreview-0.9.1.tar.gz (39.6 kB view hashes)

Uploaded source

Built Distribution

nbpreview-0.9.1-py3-none-any.whl (45.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page