https://github.com/akopdev/nbcat
Preview Jupyter notebooks directly in your terminal. Think of it as cat, but for .ipynb files.
https://github.com/akopdev/nbcat
ipynb jupyter jupyter-notebook nbcat terminal tui
Last synced: 3 months ago
JSON representation
Preview Jupyter notebooks directly in your terminal. Think of it as cat, but for .ipynb files.
- Host: GitHub
- URL: https://github.com/akopdev/nbcat
- Owner: akopdev
- License: mit
- Created: 2025-04-21T22:38:21.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-06-04T13:00:23.000Z (9 months ago)
- Last Synced: 2025-09-20T18:23:50.134Z (6 months ago)
- Topics: ipynb, jupyter, jupyter-notebook, nbcat, terminal, tui
- Language: Jupyter Notebook
- Homepage:
- Size: 7.14 MB
- Stars: 30
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-cli-apps-in-a-csv - nbcat - Preview Jupyter notebooks (ipynb) in terminal. (<a name="viewers"></a>Viewers)
- awesome-cli-apps - nbcat - Preview Jupyter notebooks (ipynb) in terminal. (<a name="viewers"></a>Viewers)
README
nbcat: Jupyter notebooks viewer
[nbcat](https://github.com/akopdev/nbcat) let you preview Jupyter notebooks directly in your terminal. Think of it as `cat`, but for `.ipynb` files.
## Features
- Very fast and lightweight with minimal dependencies.
- Preview remote notebooks without downloading them.
- Enable paginated view mode with keyboard navigation (similar to `less`).
- Supports image rendering in high resolution
- Supports for all Jupyter notebook versions, including old legacy formats.
## Motivation
The idea of previewing notebooks in a terminal is not new - there have been many previous attempts to achieve it.
However, most are either slow and overengineered with a ton of half-working features, or they're outdated and incompatible with modern Python.
I was looking for a simple tool that let me quickly render Jupyter notebooks without switching context from my terminal window or installing a ton of dependencies.
Please note, that `nbcat` doesn't aim to replace JupyterLab. If you need a full-featured terminal experience, I recommend checking out [euporie](https://euporie.readthedocs.io/) instead.
## Installation
```bash
# Install from PyPI (recommended)
$ pip install nbcat
# Install via Homebrew
$ brew tab akopdev/formulas/nbcat
$ brew install --formula nbcat
```
## Quickstart
```bash
$ nbcat notebook.ipynb
```
You can pass URLs as well.
```bash
$ nbcat https://raw.githubusercontent.com/akopdev/nbcat/refs/heads/main/tests/assets/test4.ipynb
```
In most cases system `less` will render images in low resolution. Consider using an internal pager instead:
```bash
$ nbcat notebook.ipynb --page
```
## Integrations
`nbcat` is designed to integrate seamlessly with other tools. Here are a few examples of how easily it can be done.
### FZF (Fuzzy finder)
List all `.ipynb` files and use `nbcat` to preview them:
```bash
find . -type f -name "*.ipynb" | fzf --preview 'nbcat {}'
```
### Ranger
To enable previews in Ranger, add the `ipynb` extension to the `handle_extension` function in `~/.config/ranger/scope.sh`:
```bash
...
handle_extension() {
case "${FILE_EXTENSION_LOWER}" in
ipynb)
nbcat "${FILE_PATH}" && exit 5
exit 1;;
...
```
## Testing & Development
Run the tests:
```bash
make test
```
Check code quality:
```bash
make format lint
```
## Contributing
Contributions are welcome! Please open an issue or [pull request](https://github.com/akopdev/nbcat/pulls).
## License
Distributed under the MIT License. See [`LICENSE`](./LICENSE) for more information.
## Useful Links
- 📘 Documentation: _coming soon_
- 🐛 Issues: [GitHub Issues](https://github.com/akopdev/nbcat/issues)
- 🚀 Releases: [GitHub Releases](https://github.com/akopdev/nbcat/releases)
---
Made with ❤️ by [Akop Kesheshyan](https://github.com/akopdev)