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.

Steps to add a Python virtual environment as a Jupyter kernel:

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.
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.
Activate the virtual environment.
```
$ source .venv/bin/activate
```
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.

$ 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.

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.

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

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))
```
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.
Remove the temporary smoke-test script.
```
$ rm kernel-check.py
```