Metadata-Version: 2.5
Name: nbv
Version: 0.2.0
Summary: Read-only viewing of Jupyter notebooks in the terminal or web browser.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pygments
Requires-Dist: rich >=10.15
Requires-Dist: typer >=0.12.4
Requires-Dist: nbv[image] ; extra == "complete"
Requires-Dist: nbv[tui] ; extra == "complete"
Requires-Dist: nbv[web] ; extra == "complete"
Requires-Dist: pillow ; extra == "image"
Requires-Dist: textual-image ; extra == "image"
Requires-Dist: pillow ; extra == "tui"
Requires-Dist: textual-image[textual] ; extra == "tui"
Requires-Dist: ipython ; extra == "web"
Requires-Dist: nbconvert ~=7.0 ; extra == "web"
Provides-Extra: complete
Provides-Extra: image
Provides-Extra: tui
Provides-Extra: web
Import-Name: nbv

# nbv

Read-only Jupyter Notebook viewing in the terminal or web browser.

Invoking
```
nbv notebook.ipynb
```
renders the notebook in the terminal using [Rich](https://github.com/Textualize/rich) when connected to an interactive terminal, or as strict plain text (no ANSI escape codes) when piped or redirected.

* The notebook can also be an `http://` or `https://` URL. It is downloaded to a temporary file that is removed when `nbv` exits (`--cleanup` also removes any leftovers), and GitHub `blob` links are converted to raw links automatically.
* Use `--plain`/`--no-rich` to force plain text output in a terminal, or `--rich` to force Rich ANSI output when piping (e.g. `nbv --rich notebook.ipynb | less -R`).
* If [`textual-image`](https://github.com/lnqs/textual-image) is installed, embedded images are displayed directly in the terminal (using Sixel or Kitty's Terminal Graphics Protocol when supported, falling back to colored half-cell blocks); otherwise image dimensions (e.g. `[image/png: 640x480]`) are shown.
* Use `--images` (`auto`, `sixel`, `tgp`, `halfcell`, `unicode`, `dims`, `none`) to control how images are displayed.
* Use `--theme` to choose the syntax highlighting theme: `dark` (the default) or `light`, which use the terminal's own ANSI colors (Rich's `ansi_dark`/`ansi_light`), or any other Rich/Pygments style name (e.g. `monokai`).
* Use `--tui` to browse the notebook in a scrollable full-screen [Textual](https://github.com/Textualize/textual) viewer (requires `nbv[tui]`; keys: arrows/`j`/`k`, space/`b`, `g`/`G`, `q`). Images are rendered with `textual-image`'s Textual widgets; note that Sixel images can flicker while scrolling. Set `NBV_TUI_SCROLL_DELAY` (seconds, e.g. `0.2`) to hide images while scrolling and show them again once it pauses, which avoids the flicker. Images are rescaled when the terminal is resized; set `NBV_TUI_RESIZE_DELAY` (same units) to wait until resizing pauses.

### Web browser mode (`--web`)

Invoking
```
nbv --web notebook.ipynb
```
converts the notebook to HTML[^1] using `nbconvert` and opens this HTML file in the default web browser.

You can get a similar result with just
```
nbconvert notebook.ipynb --to html --post serve
```
Note that this (and `nbv`) doesn't require a full Jupyter installation (e.g. JupyterLab) in order to run.
But `nbv --web` has additional benefits[^2]:
* doesn't pollute the notebook location with HTML (unlike the above)
* no server, just open the HTML file in browser
* simple CLI, exposing only a few `nbconvert` options

**Note:** `nbv --web` will use the [`nbconvert` library](https://nbconvert.readthedocs.io/en/stable/nbconvert_library.html) if installed, otherwise it will fall back to the `jupyter-nbconvert` [command](https://nbconvert.readthedocs.io/en/stable/usage.html).

### [uv](https://docs.astral.sh/uv/guides/tools/) examples

Terminal viewing (image dimensions fallback):
```
uvx nbv notebook.ipynb
```

Terminal viewing with image rendering (`textual-image`):
```
uvx --from 'nbv[image]' nbv notebook.ipynb
```

Terminal viewing with image rendering and scrollable viewer:
```
uvx --from 'nbv[tui]' nbv --tui notebook.ipynb
```

Web browser viewing (`nbconvert` library):
```
uvx --from 'nbv[web]' nbv --web notebook.ipynb
```

All optional dependencies (`textual-image`, `nbconvert`, `ipython`):
```
uvx --from 'nbv[complete]' nbv notebook.ipynb
```
```
uv tool install 'nbv[complete]'
```

---

[^1]: Inside the OS temporary directory by default. The file is left in place for the browser to read, so use `--cleanup` to remove old ones.
[^2]: Also I wanted to try [Typer](https://typer.tiangolo.com).

