kiyoon/jupynium.nvim

Selenium-automated Jupyter Notebook that is synchronised with Neovim in real-time.

Jupynium.nvim – Live‑preview Jupyter notebooks from inside Neovim

What it is – A Neovim plugin that lets you edit a Jupytext‑style file (*.ju.py, *.ju.*) and have every change instantly reflected in a running Jupyter Notebook opened in Firefox. It works by running a small Python‑based server that talks to the notebook through Selenium, so the notebook UI stays untouched – no kernel extensions are required.

Why it matters – Data‑scientists and developers who spend most of their time in a terminal editor can now stay in Neovim while still getting the rich, interactive view of a notebook. The sync is one‑way (Neovim → browser), which keeps the workflow simple and avoids conflicts with manual edits in the notebook UI.

Core ideas

Component	Role
Neovim plugin (Lua)	Detects `.ju.` files, provides commands, keymaps, and optional integrations (completion, folding).
Jupynium server (Python)	Receives edit events from Neovim, drives Firefox via Selenium, and updates the notebook front‑end.
Selenium + geckodriver	Automates the browser; only Firefox is supported because of Selenium limitations.
Jupytext percent format	The on‑disk file format (`# %%` for code cells, `# %% [md]` for markdown) that the plugin parses and syncs.

Key features (as described in the README)

Live preview – As you type in Neovim, the corresponding notebook cell updates instantly in the browser.
Zero‑install on the notebook side – No Jupyter extensions or kernel modifications; everything is done through the front‑end.
Supports any kernel – Because it only drives the UI, you can use Python, R, or any language that Jupyter supports.
Remote‑friendly – The notebook can run on a remote server while the Neovim client stays local (the server just needs to reach the browser).
Automatic file handling – Optional auto‑download of the .ipynb copy, auto‑close of synced tabs, and auto‑scroll to the active cell.
Rich integration – Completion sources for nvim-cmp / blink.cmp, folding via nvim-ufo, and hover information that mimics LSP hover.
Customizable keybindings and text objects – Default shortcuts (<space>x to run, <space>c to clear, etc.) can be disabled and re‑defined.
Extensible Lua API – Jupynium_execute_javascript lets plugins or user scripts run arbitrary JavaScript in the notebook context.

Installation checklist (from the README)

System requirements
- Neovim ≥ 0.8
- Firefox + matching geckodriver
- Python ≥ 3.9 (or a virtual env via uv/Conda)
- Jupyter Notebook ≥ 6.2 (classic interface; Notebook 7 not yet supported)
Python side – Install the plugin’s Python package (e.g. pip3 install --user . or using uv/Conda as shown).
Neovim side – Add the plugin with your favourite manager (vim‑plug, packer.nvim, lazy.nvim, …) and run the build step that installs the Python package.
Optional UI helpers – rcarriga/nvim-notify and stevearc/dressing.nvim for nicer notifications and selection dialogs.
Configure – Call require("jupynium").setup({ … }) in your init.lua. The defaults work for most users; Conda users only need to point python_host to the Conda runner.

Quick‑start workflow

1. Open a file named <name>.ju.py (or any pattern you configured).
2. :JupyniumStartAndAttachToServer   → launches Firefox and opens the notebook UI.
3. :JupyniumStartSync                → creates an Untitled.ipynb tab and begins syncing.
4. Edit the file – use `# %%` to start a code cell, `# %% [md]` for markdown.
5. Press <space>x to run the current cell (or select multiple cells).
6. When you’re done, :JupyniumDownloadIpynb to save a .ipynb copy, or let the auto‑download option do it for you.

All changes flow from Neovim to the browser; editing the notebook directly is discouraged because the sync is one‑way.

Typical use cases

Data‑science scripting – Write and test notebooks without leaving the terminal editor you already love.
Teaching / live coding – Show a clean, live preview of notebook cells while you type in Neovim.
Remote notebooks – Keep a local Neovim session while the notebook server runs on a remote machine (e.g., a university JupyterHub).
Multi‑language projects – Because the plugin only manipulates the UI, you can work with R, Julia, or any other Jupyter kernel.

Limitations noted in the README

Only Firefox is supported (other browsers break Selenium interactions).
Notebook 7 (the new “nbclassic” UI) is not yet supported; you must use the classic Notebook 6 interface.
Sync direction is only Neovim → browser; changes made in the browser are ignored.
The plugin does not work with JupyterLab.

Where to go from here

Keep an eye on the repository issues for upcoming Notebook 7 support.
Explore the Lua API (Jupynium_execute_javascript) to build custom actions, e.g., automatic variable inspection.
Combine with completion plugins (nvim-cmp, blink.cmp) to get kernel‑side completions inside Neovim.

Bottom line – Jupynium.nvim bridges the gap between the powerful, interactive notebook UI and the efficiency‑focused Neovim editor, letting you write, run, and preview notebook cells without ever leaving your terminal.