Jupynium: Control Jupyter Notebook on Neovim with ZERO Compromise

| | | |--|--| | || | | | | | | | | |

It's just like a markdown live preview, but it's Jupyter Notebook live preview!

Jupynium uses Selenium to automate Jupyter Notebook, synchronising everything you type on Neovim.
Never leave Neovim. Switch tabs on the browser as you switch files on Neovim.

Note that it doesn't sync from Notebook to Neovim so only modify from Neovim.

<img src=https://user-images.githubusercontent.com/12980409/221559945-46f12a38-2fb8-4156-bb94-b87e831ac8f5.gif width=100% />

How does it work?

<img src=https://user-images.githubusercontent.com/12980409/211933889-e31e844c-1cf3-4d1a-acdc-70cb6e244ee4.png width=50% />

The Jupynium server will receive events from Neovim, keep the copy of the buffer and apply that to the Jupyter Notebook by using Selenium browser automation. It interacts only through the front end so it doesn't require installing extensions on the kernel etc., which makes it possible to:

• Develop locally, run remotely (or vice versa)
• Use university-hosted Jupyter Notebook
• Use any other languages / kernels such as R

🛠️ Installation

Requirements

• 💻 Linux, macOS and Windows (CMD, PowerShell, WSL2)
• ✌️ Neovim >= v0.8
• 🦊 Firefox
  • Other browsers are not supported due to their limitation with Selenium (see #49)
• 🦎 Mozilla geckodriver
  • May already be installed with Firefox. Check geckodriver -V
• 🐍 Python >= 3.9
• 📔 Jupyter Notebook >= 6.2
  • Jupyter Lab is not supported

  • # jupyter-console is optional and used for `:JupyniumKernelOpenInTerminal`
    pip install notebook nbclassic jupyter-console
    

Important note about Notebook 7 (breaking change!)

Jupynium does not support Notebook 7 yet. In the meantime, you can change the default_notebook_URL = "localhost:8888/nbclassic" in require("jupynium").setup({ ... }) to use the classic (Notebook 6) interface with Jupynium. This is the new default setting from now on.

Don't forget to upgrade your notebook and install nbclassic (pip install --upgrade notebook nbclassic) when you set this.

Install Python

Don't have system Python 3.9? You can use uv which downloads python and creates a virtual environment.

# This downloads python 3.13 if it doesn't exist.
uv venv ~/.virtualenvs/jupynium --python=3.13

Or with Conda:

conda create -n jupynium python=3

If you want to use system python, (not conda or uv), upgrade pip. This solves many problems:

# pip >= 23.0 recommended
pip3 install --upgrade pip

Install Jupynium

<details> <summary> Click to see vim-plug and packer installation. </summary>

With vim-plug:

Plug 'kiyoon/jupynium.nvim', { 'do': 'pip3 install --user .' }
" Plug 'kiyoon/jupynium.nvim', { 'do': 'uv pip install . --python=$HOME/.virtualenvs/jupynium/bin/python' }
" Plug 'kiyoon/jupynium.nvim', { 'do': 'conda run --no-capture-output -n jupynium pip install .' }
Plug 'rcarriga/nvim-notify'   " optional
Plug 'stevearc/dressing.nvim' " optional, UI for :JupyniumKernelSelect

With packer.nvim:

use { "kiyoon/jupynium.nvim", run = "pip3 install --user ." }
-- use { "kiyoon/jupynium.nvim", run = "uv pip install . --python=$HOME/.virtualenvs/jupynium/bin/python" }
-- use { "kiyoon/jupynium.nvim", run = "conda run --no-capture-output -n jupynium pip install ." }
use { "rcarriga/nvim-notify" }   -- optional
use { "stevearc/dressing.nvim" } -- optional, UI for :JupyniumKernelSelect

</details>

With 💤lazy.nvim:

  {
    "kiyoon/jupynium.nvim",
    build = "pip3 install --user .",
    -- build = "uv pip install . --python=$HOME/.virtualenvs/jupynium/bin/python",
    -- build = "conda run --no-capture-output -n jupynium pip install .",
  },
  "rcarriga/nvim-notify",   -- optional
  "stevearc/dressing.nvim", -- optional, UI for :JupyniumKernelSelect

Configure Jupynium

The default configuration values are below and work well for system-level Python users. If you're a Conda user, you need to change python_host to execute using the conda command instead.

<details> <summary> Click to see the setup defaults </summary>

require("jupynium").setup({
  --- For Conda environment named "jupynium",
  -- python_host = { "conda", "run", "--no-capture-output", "-n", "jupynium", "python" },
  python_host = vim.g.python3_host_prog or "python3",

  default_notebook_URL = "localhost:8888/nbclassic",

  -- Write jupyter command but without "notebook"
  -- When you call :JupyniumStartAndAttachToServer and no notebook is open,
  -- then Jupynium will open the server for you using this command. (only when notebook_URL is localhost)
  jupyter_command = "jupyter",
  --- For Conda, maybe use base environment
  --- then you can `conda install -n base nb_conda_kernels` to switch environment in Jupyter Notebook
  -- jupyter_command = { "conda", "run", "--no-capture-output", "-n", "base", "jupyter" },

  -- Used when notebook is launched by using jupyter_command.
  -- If nil or "", it will open at the git directory of the current buffer,
  -- but still navigate to the directory of the current buffer. (e.g. localhost:8888/nbclassic/tree/path/to/buffer)
  notebook_dir = nil,

  -- Used to remember the last session (password etc.).
  -- e.g. '~/.mozilla/firefox/profiles.ini'
  -- or '~/snap/firefox/common/.mozilla/firefox/profiles.ini'
  firefox_profiles_ini_path = nil,
  -- nil means the profile with Default=1
  -- or set to something like 'default-release'
  firefox_profile_name = nil,

  -- Open the Jupynium server if it is not already running
  -- which means that it will open the Selenium browser when you open this file.
  -- Related command :JupyniumStartAndAttachToServer
  auto_start_server = {
    enable = false,
    file_pattern = { "*.ju.*" },
  },

  -- Attach current nvim to the Jupynium server
  -- Without this step, you can't use :JupyniumStartSync
  -- Related command :JupyniumAttachToServer
  auto_attach_to_server = {
    enable = true,
    file_pattern = { "*.ju.*", "*.md" },
  },

  -- Automatically open an Untitled.ipynb file on Notebook
  -- when you open a .ju.py file on nvim.
  -- Related command :JupyniumStartSync
  auto_start_sync = {
    enable = false,
    file_pattern = { "*.ju.*", "*.md" },
  },

  -- Automatically keep filename.ipynb copy of filename.ju.py
  -- by downloading from the Jupyter Notebook server.
  -- WARNING: this will overwrite the file without asking
  -- Related command :JupyniumDownloadIpynb
  auto_download_ipynb = true,

  -- Automatically close tab that is in sync when you close buffer in vim.
  auto_close_tab = true,

  -- Always scroll to the current cell.
  -- Related command :JupyniumScrollToCell
  autoscroll = {
    enable = true,
    mode = "always", -- "always" or "invisible"
    cell = {
      top_margin_percent = 20,
    },
  },

  scroll = {
    page = { step = 0.5 },
    cell = {
      top_margin_percent = 20,
    },
  },

  -- Files to be detected as a jupynium file.
  -- Add highlighting, keybindings, commands (e.g. :JupyniumStartAndAttachToServer)
  -- Modify this if you already have lots of files in Jupytext format, for example.
  jupynium_file_pattern = { "*.ju.*" },

  use_default_keybindings = true,
  textobjects = {
    use_default_keybindings = true,
  },

  syntax_highlight = {
    enable = true,
  },

  -- Dim all cells except the current one
  -- Related command :JupyniumShortsightedToggle
  shortsighted = false,

  -- Configure floating window options
  -- Related command :JupyniumKernelHover
  kernel_hover = {
    floating_win_opts = {
      max_width = 84,
      border = "none",
    },
  },

  notify = {
    ignore = {
      -- "download_ipynb",
      -- "error_download_ipynb",
      -- "attach_and_init",
      -- "error_close_main_page",
      -- "notebook_closed",
    },
  },
})

-- You can link highlighting groups.
-- This is the default (when colour scheme is unknown)
-- Try with CursorColumn, Pmenu, Folded etc.
vim.cmd [[
hi! link JupyniumCodeCellSeparator CursorLine
hi! link JupyniumMarkdownCellSeparator CursorLine
hi! link JupyniumMarkdownCellContent CursorLine
hi! link JupyniumMagicCommand Keyword
]]

-- Please share your favourite settings on other colour schemes, so I can add defaults.
-- Currently, tokyonight is supported.

</details>

Optionally, configure nvim-cmp / blink.cmp to show Jupyter kernel completion

nvim-cmp:

local cmp = require "cmp"
local compare = cmp.config.compare

cmp.setup {
  sources = {
    { na