nbpreview

nbpreview is a terminal viewer for Jupyter notebooks (similar to cat for .ipynb files) that provides rich rendering capabilities, including:

• Code: Syntax highlighting for code cells.
• Markdown: Rendering of markdown content.
• Images: Drawing/displaying images.
• Data: Rendering of DataFrames and Vega/Vega-Lite charts.
• Math: Rendering of LaTeX.
• Web Content: Parsing HTML and creating hyperlinks for complex content.
• Errors: Rendering of stderr output and tracebacks.
• Icons: Support for Nerd Font icons.

nbpreview provides visual formatting for error outputs:

• Stderr: Text sent to stderr is highlighted inside a bright red box.
• Tracebacks: Python tracebacks are rendered with full syntax highlighting to improve readability.

You can set default values for any nbpreview option by using its associated environment variable. This allows you to avoid specifying the same command-line flags every time you run the tool.

To find the environment variable for a specific option:

1. Check the --help output; the variable is listed after env var:.
2. Refer to the command-line usage documentation.

Environment variables set a new default, but they can still be overridden by passing the explicit command-line option during execution.

# Example: Setting the theme to 'material' via environment variable
export NBPREVIEW_THEME='material'

# Now running nbpreview without the --theme flag will use 'material'
% nbpreview notebook.ipynb

# You can still override it manually if needed
% nbpreview --theme='dark' notebook.ipynb

To preview a Jupyter notebook, use the nbpreview command or its alias nbp followed by the path to your .ipynb file. The tool accepts a single notebook path, multiple notebook paths, or input from stdin.

# Using the full command
nbpreview notebook.ipynb

# Using the alias
nbp notebook.ipynb

The primary argument for nbpreview is a Jupyter notebook (.ipynb) file path. You can provide a single file, multiple files, or use shell globs to render several notebooks at once. Additionally, nbpreview accepts notebook content via stdin, allowing you to pipe content from other tools like curl or jq directly into the previewer.

# Single file
% nbpreview notebook.ipynb

# Multiple files
% nbpreview notebook1.ipynb notebook2.ipynb

# Using globs
% nbpreview notebooks/*.ipynb

# From stdin (e.g., via curl)
% curl https://example.com/notebook.ipynb | nbpreview

# Filtering cells with jq before rendering
% jq 'with_entries(if .key == "cells" then .value |= map(select(.cell_type == "markdown")) else . end)' notebook.ipynb | nbpreview

To prevent long lines of code from being truncated by the terminal, use the --code-wrap or -q option. It is recommended to use this in conjunction with --line-numbers or -m so that wrapped lines are clearly distinguishable from actual line breaks.

# Wrap code and show line numbers
% nbpreview --code-wrap --line-numbers notebook.ipynb

You can install nbpreview using several Python package managers. uv is recommended for the easiest setup.

# Using uv (recommended)
% uv tool install nbpreview

# Using pip
% python -m pip install nbpreview

To see a complete list of all available command-line options, their expected values, and any relevant environmental variables, run the command with the --help flag.

nbpreview --help

nbpreview is a tool designed to render Jupyter Notebook cells, providing high-fidelity previews of content such as DataFrames, Vega charts, LaTeX, and syntax-highlighted code. This example demonstrates a typical workflow involving data loading with pandas, probabilistic modeling with pymc, and specialized plotting using nbpreview-compatible modules.

import pandas as pd
import pymc as pm

import model
import plots

If the notebook output is longer than the terminal, nbpreview automatically uses a pager. This behavior is automatically disabled when piping to other commands. It attempts to use a color-capable pager and respects the PAGER environment variable.

• Disable paging: Use --no-paging or -f.
• Force paging: Use --paging or -g.
• Environment Variable: Use NBPREVIEW_PAGING to configure default behavior.

# Disable paging
% nbpreview --no-paging notebook.ipynb

# Force paging
% nbpreview --paging notebook.ipynb

By default, nbpreview uses "smart output": it strips decorations (boxes, execution counts, extra spacing) when output is piped to stdout to make it usable as a preprocessor for tools like fgrep. When outputting directly to a terminal, it uses a decorated mode.

• Force plain output: Use --plain or -p.
• Force decorated output: Use --decorated or -d.
• Environment Variable: Set NBPREVIEW_PLAIN=1 to make plain rendering the default.

# Force plain output
% nbpreview --plain notebook.ipynb

# Force decorated output
% nbpreview --decorated notebook.ipynb

# Set plain as default via env var
% export NBPREVIEW_PLAIN=1