tornado 6.2 incompatible with notebook 6.4, how to fix the crash

Not specified by the original author.

TL;DR

notebook 6.4 pins tornado below 6.2, so an environment where tornado got upgraded to 6.2 anyway crashes the server on startup. Resolve it in one direction: either pip install -U notebook (which resolves to 6.5 or newer, past the pin) or pip install "tornado==6.1" to honor the old pin. Verify with jupyter notebook --version and a clean server start.

tornado 6.2 incompatible with notebook 6.4, how to fix the crash

Use this when

• The notebook server crashes on startup after tornado reached 6.2.
• The traceback shows tornado import or websocket errors inside notebook 6.4 code.
• A requirements file pins notebook 6.4 without pinning tornado.

Not for this skill when

• JupyterLab (not notebook 6.x) is crashing. Check its own tornado range.
• Kernels die. Tornado is server-side; kernel crashes are separate.

Steps

1. Confirm the pair: pip show tornado notebook | grep -E "Name|Version". Verify: tornado 6.2 with notebook 6.4.
2. Preferred: upgrade notebook out of the pinned range with pip install -U notebook (resolves to 6.5+). Verify: the version is 6.5+.
3. Alternative: pin tornado back with pip install "tornado==6.1". Verify: tornado reports 6.1.x.
4. Start the server: jupyter notebook --no-browser. Verify: it serves without a traceback.
5. Record the working pair in your requirements file. Verify: a fresh install reproduces the working combination.

Variant phrasings

tornado notebook version conflict

General phrasing. The pair must be compatible.

notebook 6.4 crash tornado

Version-tagged phrasing. Upgrade notebook past 6.4.

jupyter server tornado incompatibility

Server-side phrasing. Same pin or upgrade.

Compatibility: notebook 6.4/6.5, tornado 6.1/6.2. notebook 7 uses jupyter_server and has its own compatible ranges.

Why it happens

notebook 6.4 declared an upper bound on tornado because tornado 6.2 changed internals the old server code depended on. Resolvers that ignore or override the bound, or installs that upgrade tornado independently, produce a server whose imports fail at startup. It is a packaging conflict, not a code bug, so the fix is entirely in version selection.

Edge cases / pitfalls

• Upgrading tornado alone again later re-breaks it. Pin the pair in requirements, not just one side.
• notebook 6.5+ still has other old pins; upgrading notebook can surface the next conflict. Upgrade deliberately.
• If you actually want modern Jupyter, migrate to notebook 7 or JupyterLab instead of nursing 6.4 pins.
• Conda may refuse the combination its solver cannot satisfy. Let conda pick the pair with conda install notebook unpinned.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_-Z6dVWIziX808k5Buu71SQ

Resolved from the public thread: https://vectle.com/posts/pst_-Z6dVWIziX808k5Buu71SQ

Thread query: tornado 6.2 incompatible with notebook 6.4, how to fix the crash

TL;DR: notebook 6.4 pins tornado below 6.2, so an environment where tornado got upgraded to 6.2 anyway crashes the server on startup. Resolve it in one direction: either pip install -U notebook (which resolves to 6.5 or newer, past the pin) or pip install "tornado==6.1" to honor the old pin. Verify with jupyter notebook --version and a clean server start.

Not specified by the original author.

TL;DR

Problem: a notebook "works in my notebook" but fails when rerun from a fresh kernel, on another machine, or via nbconvert. Usual causes: the notebook is attached to the wrong kernel (the server's env, not the project's), packages were installed with !pip into a different Python, the kernel was never restarted after an install, or nothing pins the dependency versions.

When to use

You are seeing this: A Jupyter kernel is a separate process. Use this skill when you run into "Jupyter kernel-environment reproducibility: pin the kernel, lock deps, make notebooks rerun clean".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Problem: a notebook "works in my notebook" but fails when rerun from a fresh kernel, on another machine, or via nbconvert. Usual causes: the notebook is attached to the wrong kernel (the server's env, not the project's), packages were installed with !pip into a different Python, the kernel was never restarted after an install, or nothing pins the dependency versions.

1. Pin the notebook to a real environment

A Jupyter kernel is a separate process. By default a notebook often runs on the Python that hosts the Jupyter server, not your project's venv or conda env. Register your environment as a named kernel:

# Run from the KERNEL'S environment (the venv/conda env the notebook should use),
# not necessarily the env running the Jupyter server.
python -m pip install ipykernel
python -m ipykernel install --user --name PROJECT_ENV --display-name "Python (project-env)"

• --name is the internal ID (no spaces) used by Jupyter; --display-name is what you see in the kernel picker.
• Select that kernel in the notebook (Kernel > Change kernel), or create the notebook from it.
• Inspect and remove stale kernelspecs:

  jupyter kernelspec list
  jupyter kernelspec uninstall STALE_KERNEL_NAME

• Sanity check from inside a cell: import sys; print(sys.executable) should point at your project's Python.

2. Install packages into the kernel's environment

Inside a notebook cell, use the %pip magic, never !pip:

%pip install package-name

• %pip installs into the environment backing the running kernel.
• !pip runs the shell's pip, which may resolve to a different Python (e.g. the notebook server's env). The install "succeeds" but import still fails in the notebook.

3. Restart the kernel after installing anything

If import fails right after installing, restart the kernel (Kernel > Restart) and re-run the cells. And the only real reproducibility test is Restart & Run All top-to-bottom, it exposes hidden state from cells you previously ran out of order.

4. Lock the environment so someone else can recreate it

For pip/venv projects:

pip freeze > requirements.txt   # exact pins of everything installed
pip install -r requirements.txt # recreate elsewhere

For conda:

conda env export > environment.yml                # full snapshot (versions + builds)
conda env export --no-builds > environment.yml    # more portable across machines
conda env export --from-history > environment.yml # only the packages you asked for
conda env create -f environment.yml
conda activate ENV_NAME

• Check requirements.txt / environment.yml in next to the notebook.
• After recreating the env, re-register the kernel with the same --name, so the kernelspec stored in the notebook still matches on the new machine.

5. nbconvert execution gotchas when sharing

Headless execution uses the kernel recorded in the notebook's metadata

jupyter nbconvert --to notebook --execute NOTEBOOK.ipynb

• The kernel name comes from the notebook metadata. If the recipient has no kernelspec with that name, execution fails, override it: --ExecutePreprocessor.kernel_name=PROJECT_ENV.
• Per-cell timeout defaults to 30 seconds; raise it (--ExecutePreprocessor.timeout=600) or disable with -1 for long jobs.
• By default the first failing cell raises CellExecutionError and stops; --ExecutePreprocessor.allow_errors=True records errors in the output and continues.
• Executing from a clean checkout + fresh env gives the true "does it rerun" answer.

Built from the IPython/Jupyter documentation on kernel installation (ipykernel install, kernelspec management), the IPython %pip magic documentation, conda environment documentation, and the nbconvert execution documentation.

Not specified by the original author.

TL;DR: notebook 7 needs the separate jupyterserver package and it is missing. Run `pip install jupyterserver` and notebook launches.

The error

ModuleNotFoundError: No module named 'jupyter_server'

Fix it

1. Install jupyter_server:

   pip install jupyter_server

   Expected: install completes.

2. Verify:

   python -c "import jupyter_server; print(jupyter_server.__version__)"

   Expected: prints the version.

3. Launch notebook again. Expected: the server starts instead of the import error.

When this applies

Use this when jupyter notebook (version 7+) fails with the jupyter_server error, common after --no-deps installs.

When it does not apply

If you are on classic notebook 6.x, jupyterserver is not needed; a different problem is at play. If jupyterserver is installed but the error persists, check your environment.

Compatibility

notebook 7.x with jupyter_server 2.x.

Root cause

notebook 7 was rebuilt on top of jupyter_server instead of carrying its own server code. The dependency is declared, but installs that skip dependencies or partial upgrades can leave it out.

Edge cases

Installing plain pip install notebook pulls jupyter_server automatically; the error mostly hits hand-assembled envs. In conda, install notebook from conda-forge to get the matched server.

GitHub issue jupyter/notebook#5440 reports ModuleNotFoundError: No module named 'jupyterserver' when launching notebook 7 in an environment where the server package was not installed. The verified fix: notebook 7 split the server into the separate jupyterserver package, so installing it (pip install jupyter_server, which notebook 7 normally pulls in) resolved the launch. Full thread: https://github.com/jupyter/notebook/issues/5440