# How to Create Custom Jupyter Notebook Kernels for the AI-For-Beginners Curriculum

> Create custom Jupyter kernels for AI-For-Beginners. Register the ai4beg kernel to run notebooks with specific TensorFlow PyTorch and OpenCV dependencies.

- Repository: [Microsoft/AI-For-Beginners](https://github.com/microsoft/AI-For-Beginners)
- Tags: how-to-guide
- Published: 2026-08-09

---

**Register a dedicated Jupyter kernel for the `ai4beg` Conda environment using `python -m ipykernel install` to ensure all lesson notebooks execute with the curriculum's specific TensorFlow, PyTorch, and OpenCV dependencies.**

The Microsoft **AI-For-Beginners** repository provides a complete machine learning curriculum that relies on a carefully pinned Python environment defined in [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml). Creating a custom Jupyter notebook kernel for this curriculum isolates the required packages from your system Python, preventing version conflicts and guaranteeing that code cells execute identically across different student machines.

## Why You Need a Custom Kernel

The curriculum depends on specific versions of **TensorFlow**, **PyTorch**, **Keras**, and **OpenCV** listed in the [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) file at the repository root. Without a custom kernel, Jupyter may default to a different Python interpreter that lacks these dependencies or uses incompatible versions. A dedicated kernel ensures that every notebook runs against the `ai4beg` environment, maintaining reproducibility across the 24+ lessons.

## Prerequisites

Before creating the kernel, ensure you have:

- **Conda** (Anaconda or Miniconda) installed on your system
- The **AI-For-Beginners** repository cloned locally
- The [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) file present in the repository root

## Step-by-Step Kernel Creation

### Create and Activate the Conda Environment

First, build the environment from the provided specification file. This installs all required packages into an isolated prefix named `ai4beg`.

```bash
conda env create --name ai4beg --file environment.yml
conda activate ai4beg

```

*Source:* The [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) in the repository root defines the exact package constraints required by the curriculum.

### Install the IPython Kernel Package

Ensure the `ipykernel` package is available within the activated environment. This package provides the machinery Jupyter uses to communicate with the Python interpreter.

```bash
pip install --upgrade ipykernel

```

### Register the Custom Kernel

Run the following command **inside the activated `ai4beg` environment** to generate the kernel specification:

```bash
python -m ipykernel install \
    --user \
    --name ai4beg \
    --display-name "AI-For-Beginners (Python 3)"

```

- `--name ai4beg` sets the internal identifier used by Jupyter.
- `--display-name` defines the human-readable label visible in the Jupyter UI.

This command creates a kernel specification directory at `~/.local/share/jupyter/kernels/ai4beg/` on Linux and macOS, or `%APPDATA%\jupyter\kernels\ai4beg\` on Windows.

### Verify the Installation

Confirm that Jupyter recognizes the new kernel by listing all available kernelspecs:

```bash
jupyter kernelspec list

```

You should see an entry similar to:

```

ai4beg    /home/username/.local/share/jupyter/kernels/ai4beg
python3   /usr/share/jupyter/kernels/python3

```

## Customizing the Kernel Specification

To modify environment variables (such as adding the repository root to `PYTHONPATH`) or adjust the startup behavior, edit the [`kernel.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/kernel.json) file directly.

On Linux or macOS, open:

```bash
~/.local/share/jupyter/kernels/ai4beg/kernel.json

```

On Windows, open:

```bash
%APPDATA%\jupyter\kernels\ai4beg\kernel.json

```

The default structure resembles:

```json
{
    "argv": [
        "/path/to/conda/envs/ai4beg/bin/python",
        "-m",
        "ipykernel_launcher",
        "-f",
        "{connection_file}"
    ],
    "display_name": "AI-For-Beginners (Python 3)",
    "language": "python",
    "env": {}
}

```

Add environment variables under the `env` key. For example, to include the curriculum directory in `PYTHONPATH`:

```json
"env": {
    "PYTHONPATH": "/path/to/AI-For-Beginners"
}

```

## Selecting the Kernel in Notebooks

Once registered, associate any notebook with the custom environment:

1. Open a lesson notebook from the `lessons/` directory.
2. Navigate to **Kernel → Change kernel**.
3. Select **AI-For-Beginners (Python 3)**.

All subsequent cell executions will use the Python interpreter from the `ai4beg` Conda environment with the exact dependency versions specified in [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml).

## Removing the Custom Kernel

If you need to unregister the kernel (for example, to recreate it with different settings), run:

```bash
jupyter kernelspec uninstall ai4beg

```

This removes the kernel specification directory without deleting the underlying Conda environment.

## Summary

- **Create** the isolated environment using `conda env create -f environment.yml -n ai4beg` to install TensorFlow, PyTorch, and other dependencies.
- **Register** the kernel by running `python -m ipykernel install --user --name ai4beg --display-name "AI-For-Beginners (Python 3)"` inside the activated environment.
- **Locate** the generated kernel specification at `~/.local/share/jupyter/kernels/ai4beg/kernel.json` (Linux/macOS) or `%APPDATA%\jupyter\kernels\ai4beg\kernel.json` (Windows).
- **Customize** the [`kernel.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/kernel.json) file to inject environment variables like `PYTHONPATH` for shared lesson modules.
- **Select** the kernel from the Jupyter interface to ensure notebooks execute against the correct Python interpreter.

## Frequently Asked Questions

### Where is the kernel specification stored after registration?

The [`kernel.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/kernel.json) file and associated resources reside in `~/.local/share/jupyter/kernels/ai4beg/` on Linux and macOS, or `%APPDATA%\jupyter\kernels\ai4beg\` on Windows. This JSON file tells Jupyter which Python executable to launch and what environment variables to set.

### Can I use a different environment name instead of `ai4beg`?

Yes. Replace `ai4beg` with your preferred name in both the `conda create` command and the `ipykernel install` command. However, using the standard `ai4beg` name ensures consistency with curriculum documentation and troubleshooting guides.

### How do I troubleshoot kernel crashes or import errors?

First, verify the kernel points to the correct Conda environment by checking the first element of the `argv` array in [`kernel.json`](https://github.com/microsoft/AI-For-Beginners/blob/main/kernel.json)—it should reference the Python binary inside your `ai4beg` environment (e.g., `/path/to/conda/envs/ai4beg/bin/python`). Second, ensure you created the environment from the [`environment.yml`](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) file in the repository root, as this guarantees compatible library versions.

### Is the custom kernel required to complete the curriculum?

While technically you could run notebooks using a system-wide Python installation that manually has all dependencies installed, the custom kernel is **strongly recommended**. It ensures you use the exact package versions tested by the curriculum maintainers, preventing subtle bugs caused by API changes in TensorFlow or PyTorch across different versions.