How to add a Python virtual environment as a Jupyter kernel

A Python virtual environment keeps notebook dependencies separate from the interpreter that starts Jupyter Notebook. Registering the environment as a kernel lets Notebook run cells with the project's packages while the server continues to run from its own installation.

The registration is stored as a Jupyter kernelspec. ipykernel writes a small kernel.json entry that points Jupyter to the environment's python executable, so the display name appears in Notebook menus without copying packages into the Jupyter server environment.

Use a short internal kernel name such as python-analysis and a readable display name such as Python (analysis). Reusing the same --name overwrites that kernelspec, so choose a name that belongs to the project or environment.

1. Open the project directory that should own the virtual environment.

   $ cd ~/projects/analysis

   Use the path for the real project. The sample project directory is /home/analyst/projects/analysis.

2. Create the project virtual environment.

   $ python3 -m venv .venv

   Skip this step when the project already has the virtual environment that should become the Jupyter kernel.

3. Activate the virtual environment.

   $ source .venv/bin/activate

4. Install ipykernel and a small package for the smoke test inside the virtual environment.

   $ python -m pip install ipykernel humanfriendly
   Collecting ipykernel
   Collecting humanfriendly
   ##### snipped #####
   Successfully installed humanfriendly-10.0 ipykernel-7.3.0

   Replace humanfriendly with a package the notebook actually needs when validating a real project environment. Keep ipykernel installed in the environment that should run the notebook cells.

5. Register the activated virtual environment as a user-level Jupyter kernel.

   $ python -m ipykernel install --user --name python-analysis --display-name "Python (analysis)"
   Installed kernelspec python-analysis in /home/analyst/.local/share/jupyter/kernels/python-analysis

   --name is the internal kernelspec name. --display-name is the label shown in Notebook kernel menus.

6. Leave the project virtual environment when Notebook runs from another Python installation.

   $ deactivate

   Keep the environment active if Jupyter Notebook itself is installed in this virtual environment.

7. List the available Jupyter kernels.

   $ jupyter kernelspec list
   Available kernels:
     python3            /usr/local/share/jupyter/kernels/python3
     python-analysis    /home/analyst/.local/share/jupyter/kernels/python-analysis

8. Create a temporary script that checks the kernel interpreter and imports a virtual-environment package.

   kernel-check.py

   import sys
   import humanfriendly
    
   print(sys.executable)
   print(humanfriendly.format_size(2048, binary=True))

9. Run the script through the registered Jupyter kernel.

   $ jupyter run --transport=ipc --kernel python-analysis kernel-check.py
   /home/analyst/projects/analysis/.venv/bin/python
   2 KiB

   The executable path should point inside the project virtual environment. In Notebook, choose Kernel → Change kernel → Python (analysis) and run the import check in a cell.

10. Remove the temporary smoke-test script.

    $ rm kernel-check.py