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

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

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

Source: The 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.

pip install --upgrade ipykernel

Register the Custom Kernel

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

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:

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 file directly.

On Linux or macOS, open:

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

On Windows, open:

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

The default structure resembles:

{
    "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:

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

Removing the Custom Kernel

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

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}