How to troubleshoot common Jupyter Notebook errors

Jupyter Notebook errors often show up at the worst time: right before a deadline or demo. Instead of random trial and error, use a simple checklist to debug the most common issues: imports, file paths, and kernels.

1. Start with three questions

1. Did this notebook ever work on this machine?
2. Did I change environment, data, or code since then?
3. Can I reproduce the error in a minimal example?

2. ModuleNotFoundError (imports)

Typical causes:

• Package not installed in the current environment.
• Jupyter using a different interpreter than your terminal.

Basic fix inside a cell:

import sys
!{sys.executable} -m pip install package-name

Then restart the kernel and rerun imports.

3. FileNotFoundError (paths)

Checklist:

• Print os.getcwd() to see the working directory.
• Use relative paths like data/train.csv, not absolute desktop paths.
• Verify the file exists with os.listdir() in the directory you expect.

4. Kernel issues (can’t start, crashes, or “dead”)

Try:

• Restarting Jupyter / JupyterLab / VS Code.
• Creating a fresh virtual environment and installing notebook there.
• Checking for extension conflicts by running a plain Jupyter Notebook server.

5. Protect yourself with reproducible snapshots

The best time to create a snapshot is right after you get a notebook working. NoteCapsule helps you do that with a single call:

from notebookcapsule import create_capsule

create_capsule(
    name="known-good-state",
    notebook_path="notebook.ipynb",
    data_dirs=["./data"],
    base_dir=".",  # project root
)

The Capsule contains a copy of the notebook, an environment snapshot, a data manifest, and metadata – a solid starting point if something breaks later.