jupynvim

Open .ipynb files in Neovim and edit them like a real notebook. Cells with borders, inline images, real Jupyter kernels, and an LSP that actually understands the file. Built on a Rust backend that talks the Jupyter wire protocol directly, with no Python remote-plugin layer.

It also works over SSH: point it at a remote machine or an HPC cluster and the editor stays local while files, kernels, terminals, and search run on the remote. The demo below is a remote session.

https://github.com/user-attachments/assets/2a3fbd17-561d-4c37-b856-a912944f88f8

Highlights

• Open and save .ipynb files natively. :w writes nbformat v4 JSON, and

• Cells render as visual blocks with virtual-line borders and execution-count

• Real Jupyter kernels via the wire protocol over ZMQ with HMAC-SHA256.

• Inline images using the Kitty graphics protocol. Native PNG placement, not

• Markdown cells render with their own highlight overlay. Embedded

• LSP that works on .ipynb. basedpyright, pyright, pylsp, or ruff attach

• LSP notebook protocol for notebook-aware servers (Astral's ty, future

• Kernel-driven completion and hover for any language. A virtual LSP proxies

• Auto-detect a project-local .venv. If a notebook lives next to (or

• Multi-image markdown cells are supported. <leader>nD deletes one image

• Remote over SSH. Connect to a machine or HPC cluster and edit notebooks

• Per-cell execution timing. Each run shows an elapsed-time badge in the

• One Rust binary, one Lua plugin. No pynvim, no jupyter_client, no

Requirements

• Neovim 0.11 or newer.
• A terminal that implements the Kitty graphics protocol with Unicode

• Rust toolchain (cargo) only on platforms without a prebuilt binary.

• A Jupyter kernel installed for the language you intend to use. See below.
• ImageMagick 7 (magick) is required for animated GIF playback. Static

• For tmux users: enable Kitty-graphics passthrough in your tmux config:

set -g allow-passthrough on

Without this, image cells render as blank space because tmux drops the Kitty graphics escapes. Set JUPYNVIMDISABLETMUX_PASSTHROUGH=1 if you have TMUX set but are not actually inside a multiplexer.

jupynvim auto-switches image_renderer = "kitty" to "placeholder" inside tmux because direct placement places at fixed screen coords and doesn't auto-clean. Set JUPYNVIMFORCEKITTYINTMUX=1 to override.

chafa is optional. Install it if you want an ASCII-art fallback for terminals without graphics support.

Kernels

Install the kernel for whichever language you plan to run. jupynvim picks up anything that shows in jupyter kernelspec list.

# Python (one per env you want to use)
pip install ipykernel
Julia
julia -e 'using Pkg; Pkg.add("IJulia")'
R
R -e 'install.packages("IRkernel"); IRkernel::installspec()'

Kernel-driven completion and hover work as soon as the kernel is running. The editor-side LSPs covered above (basedpyright for Python, julials for Julia, rlanguageserver for R) are optional and live in your normal nvim-lspconfig / mason setup. Install them through :Mason like any other language server. Julia and R additionally need the underlying language package installed in their own runtimes, since mason only ships the wrappers:

# Julia, inside the project's environment
using Pkg; Pkg.add("LanguageServer")

# R
install.packages("languageserver")

Install

With lazy.nvim:

{
  "sheng-tse/jupynvim",
  build = function(plugin)
    local install = loadfile(plugin.dir .. "/lua/jupynvim/install.lua")()
    install.run(plugin)
  end,
  config = function()
    require("jupynvim").setup({
      log_level = "info",
      image_renderer = "placeholder",  -- "placeholder", "kitty", or "chafa"
    })
  end,
}

That's it. Open any .ipynb and the kernel auto-starts based on the notebook's kernelspec metadata.

Security of the prebuilt binary

The build step downloads jupynvim-core from the GitHub release over HTTPS and runs it. HTTPS protects the download in transit; on top of that the installer checks the binary against the release's published SHA256SUMS and refuses to run it (building from source instead) if the hash does not match or the binary is not listed, which catches a corrupted, swapped, or unlisted binary. Releases older than this check publish no SHA256SUMS, and the installer warns and proceeds for those. It does not yet catch a release where both the binary and SHA256SUMS were replaced; signature verification for that is on the roadmap. If you would rather not trust the prebuilt at all, point core_path at a binary you built yourself, or build from source (the installer falls back to cargo build on unsupported platforms).

Quick start

Open an existing notebook with :edit my-notebook.ipynb or create a fresh one with :JupynvimOpen new-notebook.ipynb.

Inside the buffer, move your cursor into a code cell and press <leader>nr or <S-CR>. The execution count badge cycles to [*], then [1], and the output appears below the code framed by the same border. <leader>nb adds a code cell below, <leader>nm converts it to markdown, and <leader>nK opens a picker listing every installed kernelspec.

:w saves. :wqa works as expected even if you only ran cells. jupynvim flips the modified flag on every output event so vim's "unchanged" check doesn't skip the save.

Remote workspace (SSH)

Point jupynvim at a remote machine and the editor runs locally while the notebook, its kernel, the file tree, terminals, and search all run on the remote. Only jupynvim-core runs there; cursor motion and rendering never cross the link. It is built on plain ssh (one connection, multiplexed), so it works on clusters where SFTP/scp are disabled and inbound ports are firewalled. It is tested against PSC Bridges-2.

Declare a profile in setup:

require("jupynvim").setup({
  remote = {
    cluster = {
      host = "user@cluster.example.edu",   -- or an ~/.ssh/config Host alias
      core_path = "~/.local/bin/jupynvim-core",
      -- ssh_args = { "-J", "jumpbox" },    -- optional ProxyJump etc.
    },
  },
})

Then connect and open a notebook:

:JupynvimConnect cluster
:JupynvimOpenRemote cluster:~/work/train.ipynb

:JupynvimConnect opens a short-lived terminal split for the SSH handshake (password, 2FA) and sets up a ControlMaster socket, so it survives nvim restarts and later opens reuse it without re-authenticating. With no argument it shows a picker; a bare user@host (or any ~/.ssh/config Host) connects ad hoc. The Linux backend binary is cross-built (:JupynvimCrossBuild) and uploaded to core_path automatically when it is missing or out of date.

Once connected:

• Files. Remote paths use the jupynvim://<alias>/<path> URI scheme.

• Terminals, VSCode-style. A bottom PTY shell (:JupynvimTerm or

• Search. :JupynvimGrep <alias> <pattern> [<path>] runs ripgrep on the

• Slurm. :JupynvimUseJob <alias> [<jobid>] routes the kernel through an

• Multiple remotes. Local and several remotes coexist, each buffer routed

Concepts

A jupynvim buffer is one Neovim buffer per .ipynb file. Cells are line ranges separated by an invisible marker, # %%[jupynvim:cell-sep], concealed at runtime. Cell type, execution count, and outputs live as state on the notebook object. The buffer text contains only what you'd type as the cell's source.

Cells aren't floating windows or scratch buffers. Splits, marks, motions, and search all work like a normal buffer. The visual block appearance comes from extmark virtual text, not separate windows.

The Rust backend (jupynvim-core) owns the Jupyter connection. It runs as a single subprocess and is shared across every open notebook. Kernel events flow back as msgpack-RPC notifications which the Lua side maps to cells.

When you open a notebook, jupynvim reads the file via the backend (round-tripping unknown nbformat fields), creates a buffer with buftype=acwrite so :w routes through our BufWriteCmd, auto-starts the kernel from the notebook's kernelspec.name, and manually attaches LSP. Neovim's built-in vim.lsp.enable callback bails on non-empty buftype, so jupynvim replicates the FileType callback's logic without that guard, then injects the kernel's pythonPath and analysis.extraPaths (harvested from python -c "import sys") so import resolution matches the env you'll actually run.

Commands

| Command | Description | |---|---| | :JupynvimOpen <path> | Open a notebook. Also handles :edit *.ipynb. | | :JupynvimRunCell | Run the cell under cursor. | | :JupynvimRunAll | Run every code cell in order. | | :JupynvimKernel | Pick a kernelspec from the installed list. | | :JupynvimRestart | Restart the active kernel. | | :JupynvimClearOutputs | Clear outputs from every code cell. | | :JupynvimClearCellOutput | Clear output for the current cell only. | | :JupynvimSaveImage [path] | Save the current cell's image to disk. | | :JupynvimDeleteImage | Delete an embedded image from a markdown cell. | | :JupynvimImageMode {placeholder\|kitty\|chafa} | Switch image renderer at runtime. | | :JupynvimReset | Close every session, wipe state, reload current buffer. | | :JupynvimDebug | Print buffer/cell/notebook state. | | :JupynvimConnect [<alias>] | Connect to a remote (picker, configured profile, or user@host). | | :JupynvimOpenRemote <alias>:<path> | Open a notebook or file on a connected remote. | | :JupynvimExplorer | File browser for the active remote tree. | | :JupynvimTerm | Toggle a PTY terminal on the remote (local when not connected). | | :JupynvimGrep <alias> <pattern> [<path>] | ripgrep the remote into the quickfix list. | | :JupynvimRemoteCd <path> | Change the remote working directory. | | :JupynvimUseJob <alias> [<jobid>] | Route the kernel through a Slurm srun overlay. | | :JupynvimUseLocal | Switch the active backend back to local. | | :JupynvimDisconnect [<alias>] | Tear down a remote connection. |

Keymaps

All notebook keymaps are buffer-local. They only exist while you're inside an .ipynb.

Cell execution

| Key | Action | |---|---| | <S-CR> or <leader>nr | Run cell, advance to next | | <C-CR> | Run cell, stay | | <leader>nR | Run all cells | | <leader>nA or <leader>nB | Run all cells above or below |

Cell editing

| Key | Action | |---|---| | <leader>na or <leader>nb | Add cell above or below | | <leader>nd | Delete cell | | <leader>nk or <leader>nj | Move cell up or down | | <leader>nm or <leader>ny | Convert to markdown or code | | <leader>nc or <leader>nC | Clear current cell output, or clear all | | ]c or [c | Jump to next or prev cell |

Outputs and images

| Key | Action | |---|---| | <C-j> or <C-k> | Enter the next or prev cell's output in a scratch split with full vim motions | | <leader>nI | Save current cell's image to file | | <leader>nD | Delete an embedded image from a markdown cell | | ]i or i | Jump to next or prev cell with an image |

require("jupynvim").setup({
  -- Verbosity for both the Rust backend and the Lua frontend.
  log_level = "info",  -- trace, debug, info, warn, or error
-- How code-cell outputs and embedded markdown images are rendered.   --   "placeholder" uses the Kitty Unicode placeholder protocol. The image   --                 is anchored to buffer text and stays put when scrolling.   --                 Required for animated GIFs.   --   "kitty"       uses direct kitty placement. Lives at fixed screen   --                 coordinates and doesn't follow scroll.   --   "chafa"       is an ASCII-art fallback. Use this on terminals without   --                 graphics support.   image_renderer = "placeholder",
-- Inline image grid size in terminal cells (rows x cols). Default 16x48;   -- bump for sharper output on large terminals or shrink for compact display.   image_rows = 16,   image_cols = 48,
-- Override the path to the jupynvim-core binary. Auto-detected from the   -- plugin directory if unset.   core_path = nil,
-- Per-action keymap overrides. Pass a string to replace the default lhs   -- (mode and description preserved), false to disable a binding. The   -- full action list lives in lua/jupynvim/keymaps.lua.   keymaps = {     -- run_advance = "<leader>jr",  -- example: rebind run-and-advance     -- move_up = false,             -- example: disable move-cell-up   },
-- Skip the entire default keymap set if you want to bind everything yourself.   disabledefaultkeymaps = false,
-- Walk up from the notebook's directory to find a .venv/bin/python (or   -- .venv/Scripts/python.exe on Windows) and use it as the kernel   -- interpreter when ipykernel is installed there. Bypasses needing to   -- register a per-project user kernel. Set false to use only registered   -- kernelspecs.   auto_venv = true,
-- LSP servers to skip on jupynvim buffers. Useful for servers that   -- misbehave on .ipynb URIs without advertising notebook capability.   -- Notebook-aware servers (anything with notebookDocumentSync) are   -- handled correctly via the LSP notebook protocol and don't need to be   -- listed here.   lsp_blocklist = {},
-- Restore animated (smooth) scrolling inside notebook buffers. Off by   -- default so cell navigation is one-shot and frames stay aligned. Set true   -- if you use snacks.scroll and want it back in notebooks.   smooth_scroll = false,
-- Named remote profiles for :JupynvimConnect / :JupynvimOpenRemote. Key is   -- the alias; value is the connection spec.   remote = {     -- cluster = {     --   host = "user@cluster.example.edu",  -- or an ~/.ssh/config Host     --   core_path = "~/.local/bin/jupynvim-core",     --   -- ssh_args = { "-J", "jumpbox" },     -- },   },
-- Borrowed only while a remote session is active. If you already have a   -- mapping for one of these, jupynvim takes it on connect and gives it back   -- exactly on disconnect; if you don't, it stays bound and falls back to the   -- local equivalent. Set a group to {} to leave those keys alone entirely.   explorer_keys     = { "<leader>e" },  -- remote tree at the project root   explorercwdkeys = { "<leader>E" },  -- remote tree at the remote cwd   terminalkeys = { "<c-/>", "<c->" },           -- toggle a remote PTY   pick_keys = {     files = { "<leader>ff", "<leader><space>" },     grep  = { "<leader>/", "<leader>sg" },   }, })

Neovim (Lua frontend)
           |
           |  msgpack-rpc over stdio
           v
  jupynvim-core (Rust backend)
           |
           |  ZMQ + HMAC-SHA256, Jupyter wire protocol
           v
         ipykernel

Neovim + Lua frontend (local)
           |
           |  msgpack-rpc over ssh stdio (one multiplexed connection)
           v
  jupynvim-core (remote)  ->  ZMQ  ->  ipykernel (remote)

[Magma and molten-nvim proved that Jupyter in Neovim is a real workflow worth investing in. The Jupyter team documented an excellent wire protocol. Kitty and Ghostty built the graphics protocol that makes terminal-native notebooks possible at all.

License

MIT. See LICENSE.