nbvim

Vim-inspired terminal UI for editing and running Jupyter .ipynb notebooks.

Open or create a notebook, move between cells with vim-like keys, and run Python in your active environment.

Demo

A short Kitty recording against the analysis-test QA notebook: opening the notebook, navigating past a markdown table, running cells with r through a persistent kernel, a pandas table, and a matplotlib chart rendered with the Kitty graphics protocol.

Download the MP4

Requirements

• Python 3.13+
• pipx to install the app, or uv to develop it

Install

pipx install nbvim
nbvim path/to/notebook.ipynb

Upgrade:

pipx upgrade nbvim

Until the package is on PyPI, or to install from git:

pipx install git+https://github.com/arthuralbarelli/nbvim.git
pipx upgrade nbvim

A specific tag:

pipx install git+https://github.com/arthuralbarelli/nbvim.git@v0.1.0

Development

uv sync
uv run nbvim path/to/notebook.ipynb

If the path does not exist, nbvim creates a new notebook there before the UI starts.

Keybindings

Bindings apply in navigation mode unless noted.

r on the last cell inserts a new code cell below and focuses it. A failed run stays on the current cell. On markdown, r / R skip the kernel: r still advances, R stays.

Edit mode

The cell editor uses vim Insert, Normal, and Visual modes.

In Visual, d/x delete the selection, y yanks it, and c deletes it and enters Insert.

Commands

Leaving the UI any other way saves the notebook automatically.

Kernel

r executes the focused code cell in a persistent Jupyter Python kernel.

The kernel uses the interpreter from --python, or else the active environment (VIRTUAL_ENV, then CONDA_PREFIX). It never uses the interpreter running nbvim, and it does not guess a project .venv. If nothing is active, the editor still opens and running a cell reports an error.

PNG, JPEG, GIF, and WebP display outputs are rendered with the terminal's native graphics protocol when available (Kitty TGP or Sixel). Terminals without those protocols fall back to colored Unicode blocks. Images fill the available output width. matplotlib figures are captured at retina resolution.

Try the included demo with:

uv run nbvim demo.ipynb

The target environment needs ipykernel installed.

source .venv/bin/activate
nbvim path/to/notebook.ipynb

nbvim --python /path/to/python path/to/notebook.ipynb

Develop

make format   # Black
make lint     # Black --check

Release

Do not bump version in pyproject.toml for a release. After this workflow is on master, tag vX.Y.Z and push the tag; CI publishes that version to PyPI.

git checkout master
git pull
git tag -a v0.1.0 -m v0.1.0
git push origin v0.1.0

.github/workflows/publish.yml runs on v* tags. It sets the package version from the tag (v0.1.0 → 0.1.0) with uv version, then uv build, then publishes with PyPI trusted publishing (OIDC). No PyPI token is stored in the repo.

The version field in pyproject.toml is only a local default. The first release is 0.1.0. Later tags such as v0.2.0 do not need a matching commit that edits pyproject.toml.

One-time PyPI trusted publisher

Do this once, then merge the publish workflow, then push v0.1.0.

1. GitHub environment named pypi (no secrets): Settings → Environments → New environment
2. PyPI pending publisher at https://pypi.org/manage/account/publishing/ (the nbvim project does not exist yet):
   • PyPI project name: nbvim
   • Owner: arthuralbarelli
   • Repository name: nbvim
   • Workflow name: publish.yml
   • Environment name: pypi

The first successful upload creates https://pypi.org/project/nbvim/ .