ipykernel provides the IPython kernel, which serves as the Python execution backend for Jupyter Notebooks, JupyterLab, and other Jupyter frontends. It facilitates interactive Python development, supports rich media outputs, and enables seamless code sharing within these environments. The current stable version is 7.2.0, and the project maintains an active development and release cadence.
Install & Compatibility
Where this runs
tested against v7.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 2.243s · 96.9MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 7.1s · import 2.048s · 81MB
93MB installed
● package 93MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
embed_kernel
✓ from ipykernel.embed import embed_kernel
Used for embedding an IPython kernel into a Python application, not typically for general Jupyter usage.
The primary use case for ipykernel is to provide a Python execution environment for Jupyter frontends. This quickstart demonstrates how to install ipykernel and register it as a new kernel in your current Python environment, making it available in Jupyter Notebook or JupyterLab. It's best practice to perform this within an activated virtual environment.
import subprocess
import sys
import os
# Ensure ipykernel is installed in the current environment
subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'ipykernel'])
# Define a unique name for your kernel (e.g., based on virtual environment name)
env_name = os.environ.get('VIRTUAL_ENV', 'default_env').split(os.sep)[-1]
display_name = f"Python ({env_name.replace('_', ' ').title()} Environment)"
# Register the kernel with Jupyter
try:
subprocess.check_call([
sys.executable, '-m', 'ipykernel', 'install',
'--user', f'--name={env_name}', f'--display-name={display_name}'
])
print(f'Successfully registered Jupyter kernel: "{display_name}" (name: {env_name})')
print('To use it, launch Jupyter Notebook/Lab and select this kernel for a new notebook.')
print('You can verify installed kernels with: jupyter kernelspec list')
except subprocess.CalledProcessError as e:
print(f'Failed to register kernel: {e}')
print('Ensure Jupyter is installed (pip install notebook or pip install jupyterlab).')
Debug
Known issues
breakingipykernel 7.0.0 introduced significant architectural changes for kernel subshells, including handling shell channel messages in a separate thread. While intended to be backward compatible for non-subshell users, these changes may break assumptions made by downstream libraries. Users encountering issues should consider pinning to `ipykernel < 7`.fixIf issues arise, downgrade to `ipykernel < 7`. Review your code for assumptions about thread-local state or message timing. Consult the official changelog and GitHub issues for detailed migration guidance.
affects: 7.0.0 and later
breakingSupport for Python 3.9 was dropped in `ipykernel 7.0.0a3`. Users on Python 3.9 or older must use `ipykernel` version 6.x or earlier.fixUpgrade your Python environment to 3.10 or newer, or pin `ipykernel < 7.0.0a3` (e.g., `pip install 'ipykernel<7'`).
affects: 7.0.0a3 and later
gotchaVersion 6.30.0 contained a bug that allowed control messages to be handled concurrently, which severely broke debugging in JupyterLab and VSCode. This was a critical regression fixed in version 6.30.1.fixEnsure you are running `ipykernel` 6.30.1 or later if you were affected by this bug.
affects: 6.30.0
gotchaPrior to 7.1.0 (and 6.31.0 for the 6.x series), display outputs from magics like `%notebook` were not always included when saving sessions to `.ipynb` files, as `ZMQDisplayPublisher.store_display_history` defaulted to `False`.fixUpgrade to `ipykernel 7.1.0` or `6.31.0` (or newer). If using an older version, you may need to manually configure `ZMQDisplayPublisher.store_display_history` if exposed.
affects: < 7.1.0 and < 6.31.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ipykernel'
The `ipykernel` package is not installed in the specific Python environment that Jupyter Notebook or JupyterLab is trying to use.
fixActivate the desired Python environment and run `pip install ipykernel` (or `conda install ipykernel` if using Anaconda), then register the kernel with `python -m ipykernel install --user --name myenv --display-name "Python (myenv)"` (replace `myenv` and display name as appropriate).
Kernel Died
A generic error indicating that the Jupyter kernel failed to start or unexpectedly stopped. This can be caused by missing or incompatible dependencies (like `pyzmq`), an incorrect Python interpreter selected, a corrupted kernel specification, or resource limitations.
fixEnsure `ipykernel` is installed and registered in the correct Python environment. Check Jupyter's output logs for more specific errors. Try upgrading/downgrading `pyzmq` (`pip install --upgrade pyzmq` or `pip install pyzmq==19.0.2`) or `tornado` if dependency issues are suspected, and verify the Python executable path in the kernel configuration.
Running cells with 'Python X.Y.Z' requires the ipykernel package.
This message, often seen in IDEs like VS Code, indicates that the selected Python interpreter for the notebook does not have `ipykernel` installed.
fixExecute the recommended command provided by the IDE, usually `"<path_to_python_executable>" -m pip install ipykernel` or simply `pip install ipykernel` in the activated terminal for that environment.
A connection to the notebook server could not be established.
The Jupyter frontend cannot establish or maintain a connection with the `ipykernel` process. This can be due to network issues, port conflicts, security software interference, or a crashed kernel.
fixCheck for firewall or VPN interference. Try changing between `localhost` and `127.0.0.1` in the browser URL. Ensure no other applications are using the same port. If the kernel is dying, refer to the 'Kernel Died' fix.
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.