Jupyter_Ascending.nvim

A Neovim plugin for seamless integration with Jupyter notebooks through Jupyter Ascending. This plugin allows you to edit and execute Jupyter notebooks using regular Python files while maintaining synchronization with the notebook format.

Features

• Automatic synchronization between .sync.py files and .ipynb notebooks
• Execute individual cells or entire notebooks
• Restart Jupyter kernels
• Smart cursor-based cell execution
• Configurable auto-sync on save

Prerequisites

• Neovim >= 0.10.0
• Python >= 3.10
• Jupyter Ascending package (pip install git+https://github.com/RitschAlex/jupyter_ascending.git or pip install jupyter_ascending)

Note: The PyPI package imbue-ai/jupyter_ascending is unmaintained and only supports Jupyter Notebook v6. The GitHub installation recommended above, RitschAlex/jupyter_ascending, is a fork of imbue-ai/jupyter_ascending and supports Jupyter Notebook v7+, nbclassic and JupyterLab.

Installation

Using lazy.nvim:

{
    "RitschAlex/jupyter_ascending.nvim",
    config = function()
        require("jupyter_ascending").setup()
    end,
}

Using vim.pack

vim.pack.add({
    "RitschAlex/jupyter_ascending.nvim"
})

require("jupyter_ascending").setup()

Using packer.nvim:

use {
    "RitschAlex/jupyter_ascending.nvim",
    config = function()
        require("jupyter_ascending").setup()
    end
}

Configuration

The plugin comes with sensible defaults but can be customized using the setup function:

require("jupyter_ascending").setup({
    -- Boolean to enable or disable the plugin (default: false)
    enabled = false,

    -- Path to Python executable (default: "python")
    python_executable = "python",
    
    -- Pattern to match sync files (default: ".sync.py")
    match_pattern = ".sync.py",
    
    -- Auto-sync on save (default: true)
    auto_write = true,
    
    -- Enable default keymaps (default: true)
    default_mappings = true,
    
    -- Command timeout in milliseconds (default: 10000)
    timeout = 10000,

    -- Keymap Prefix (default: "<space><space>")
    keymap_prefix = "<space><space>",

    -- Command Line Prefix (default: "Jupyter")
    command_prefix = "Jupyter",
})

Default Keymaps

When default_mappings is enabled, the following keymaps are available in .sync.py files:

Keymap	Description
<space><space>x	Execute current cell
<space><space>X	Execute all cells
<space><space>r	Restart Jupyter kernel

API

The plugin exposes the following Lua functions:

-- Sync the current file with its corresponding Jupyter notebook
require("jupyter_ascending").sync()

-- Execute the current cell
require("jupyter_ascending").execute()

-- Execute all cells in the current file
require("jupyter_ascending").execute_all()

-- Restart the Jupyter kernel
require("jupyter_ascending").restart()

Custom Keymaps

If you prefer to set up your own keymaps, disable the default mappings in the setup and define your own:

require("jupyter_ascending").setup({
    default_mappings = false,
})

-- Set up custom keymaps
vim.keymap.set("n", "<leader>je", function()
    require("jupyter_ascending").execute()
end, { desc = "Execute current Jupyter cell" })

vim.keymap.set("n", "<leader>ja", function()
    require("jupyter_ascending").execute_all()
end, { desc = "Execute all Jupyter cells" })

vim.keymap.set("n", "<leader>jr", function()
    require("jupyter_ascending").restart()
end, { desc = "Restart Jupyter kernel" })

Usage

1. Create a Synced File Pair

Generate a .sync.py / .sync.ipynb file pair from the command line:

python -m jupyter_ascending.scripts.make_pair --base example

This creates two linked files:

File	Purpose
example.sync.py	Python source you edit in Neovim
example.sync.ipynb	Jupyter notebook kept in sync automatically

2. Launch Jupyter

Start the notebook server and open the .sync.ipynb file:

Standard Jupyter:

python -m jupyter notebook example.sync.ipynb

nbclassic (legacy interface):

python -m jupyter nbclassic

Note: When using nbclassic, the notebook must be accessible at
localhost:8888/nbclassic/notebooks.

3. Edit in Neovim

Open example.sync.py in Neovim. The plugin ships disabled by default — activate it with:

:JupyterEnable

4. Interact with the Notebook

Use keymaps or commands to control execution directly from Neovim.

Keymaps (active in .sync.py buffers):

Key	Action
<space><space>x	Execute current cell
<space><space>X	Execute all cells
<space><space>r	Restart Jupyter kernel

Commands:

Command	Effect
:JupyterSync	Sync .py → .ipynb
:JupyterExecute	Execute current cell
:JupyterExecuteAll	Execute all cells
:JupyterRestart	Restart kernel
:JupyterEnable	Enable the plugin
:JupyterDisable	Disable the plugin

Auto‑sync: When auto_write = true (the default), saving the Python file
automatically syncs changes to the notebook.

Planned future enhancements

The following features are planned for jupyter_ascending.nvim:

• Add cell below
• Add cell above

In addition, while improving Jupyter Ascending, the following core features will be added:

• Run all cells above
• Run all cells below
• Hide output
• Clear outputs
• Clear all outputs

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see the LICENSE file for details.

Acknowledgments

• Jupyter Ascending for the core functionality
• The Neovim community for inspiration and support