nb-venv-kernels 1.0.11

Jupyterlab extension to detect notebook kernels similarly to how nb_conda_kernel does

nb_venv_kernels

Use Python virtual environments as Jupyter kernels. Discovers and registers kernels from venv, uv, and conda environments in JupyterLab's kernel selector.

Features

• Unified kernel discovery - conda, venv, and uv environments in one kernel selector
• Auto-detection - distinguishes uv from venv via pyvenv.cfg
• Smart ordering - current environment first, then conda, uv, venv, system
• Drop-in replacement - replaces nb_conda_kernels while preserving all conda functionality
• CLI management - register, unregister, and list environments
• Zero config - auto-enables on install, works immediately

Install

This package should be installed in the environment from which you run Jupyter Notebook or JupyterLab. This might be your base conda environment, but it need not be. For instance, if you have a dedicated jupyter_env environment:

conda activate jupyter_env
pip install nb_venv_kernels

Or install directly with pip/uv if not using conda:

pip install nb_venv_kernels

The extension auto-enables as the default kernel spec manager via jupyter_config.json. If nb_conda_kernels is installed, nb_venv_kernels takes precedence and includes all conda kernel discovery functionality.

Usage

Virtual environments require ipykernel installed to be discoverable. The ipykernel package creates the kernel spec at {env}/share/jupyter/kernels/*/kernel.json.

# In your virtual environment
pip install ipykernel

Then register the environment:

nb_venv_kernels register /path/to/.venv
nb_venv_kernels list
nb_venv_kernels unregister /path/to/.venv

Manage Jupyter configuration:

nb_venv_kernels config enable     # Enable VEnvKernelSpecManager
nb_venv_kernels config disable    # Disable VEnvKernelSpecManager
nb_venv_kernels config show       # Show current config status

Registered environments with ipykernel appear in JupyterLab's kernel selector.

Environment Registries

Environments are registered in separate files based on their source:

• venv: ~/.venv/environments.txt
• uv: ~/.uv/environments.txt
• conda: ~/.conda/environments.txt + global environments from conda env list

The register command auto-detects uv environments via pyvenv.cfg and writes to the appropriate registry.

How It Works

flowchart LR
    subgraph Registries
        VENV[~/.venv/environments.txt]
        UV[~/.uv/environments.txt]
        CONDA_REG[~/.conda/environments.txt]
    end

    subgraph Auto-Discovery
        CONDA_ENV[conda env list]
        PYVENV[pyvenv.cfg]
    end

    subgraph Discovery
        KSPM[VEnvKernelSpecManager]
        CKSPM[CondaKernelSpecManager]
    end

    VENV --> KSPM
    UV --> KSPM
    PYVENV -.->|detects uv| UV
    CONDA_REG --> CKSPM
    CONDA_ENV --> CKSPM
    CKSPM --> KSPM
    KSPM --> JL[JupyterLab Kernel Selector]

    style VENV stroke:#10b981,stroke-width:2px
    style UV stroke:#a855f7,stroke-width:2px
    style CONDA_REG stroke:#f59e0b,stroke-width:2px
    style CONDA_ENV stroke:#f59e0b,stroke-width:2px
    style PYVENV stroke:#6b7280,stroke-width:2px
    style KSPM stroke:#3b82f6,stroke-width:3px
    style CKSPM stroke:#f59e0b,stroke-width:2px
    style JL stroke:#0284c7,stroke-width:3px

• Scans {path}/share/jupyter/kernels/*/kernel.json for each registered environment
• Configures kernel to use venv's python directly with VIRTUAL_ENV and PATH environment variables
• Kernel order: current environment first, then conda, uv, venv, system
• Caches results for 60 seconds
• config enable backs up existing config, config disable restores from backup

Configuration

Optional settings in jupyter_server_config.py:

c.VEnvKernelSpecManager.venv_only = True                      # Hide system/conda kernels
c.VEnvKernelSpecManager.env_filter = r"\.tox|\.nox"           # Exclude by pattern
c.VEnvKernelSpecManager.name_format = "{language} [{source} env:{environment}]"  # Default format

Display name variables: {language}, {environment}, {source} (uv/venv), {kernel}, {display_name}

Uninstall

pip uninstall nb_venv_kernels

After uninstall, nb_conda_kernels (if installed) will resume handling kernel discovery.