notebook/docs/source/troubleshooting.rst

What to do when things go wrong

First, have a look at the common problems listed below. If you can figure it out from these notes, it will be quicker than asking for help.

Check that you have the latest version of any packages that look relevant. Unfortunately it's not always easy to figure out what packages are relevant, but if there was a bug that's already been fixed, it's easy to upgrade and get on with what you wanted to do.

Jupyter fails to start

• Have you installed it? ;-)
• If you're using a menu shortcut or Anaconda launcher to start it, try opening a terminal or command prompt and running the command jupyter notebook.
• If it can't find jupyter, you may need to configure your PATH environment variable. If you don't know what that means, and don't want to find out, just (re)install Anaconda with the default settings, and it should set up PATH correctly.
• If Jupyter gives an error that it can't find notebook, check with pip or conda that the notebook package is installed.
• Try running jupyter-notebook (with a hyphen). This should normally be the same as jupyter notebook (with a space), but if there's any difference, the version with the hyphen is the 'real' launcher, and the other one wraps that.

Jupyter doesn't load or doesn't work in the browser

• Try in another browser (e.g. if you normally use Firefox, try with Chrome). This helps pin down where the problem is.
• Try disabling any browser extensions and/or any Jupyter extensions you have installed.
• Some internet security software can interfere with Jupyter. If you have security software, try turning it off temporarily, and look in the settings for a more long-term solution.
• In the address bar, try changing between localhost and 127.0.0.1. They should be the same, but in some cases it makes a difference.

Jupyter can't start a kernel

Files called kernel specs tell Jupyter how to start different kinds of kernel. To see where these are on your system, run jupyter kernelspec list:

$ jupyter kernelspec list
Available kernels:
  python3      /home/takluyver/.local/lib/python3.6/site-packages/ipykernel/resources
  bash         /home/takluyver/.local/share/jupyter/kernels/bash
  ir           /home/takluyver/.local/share/jupyter/kernels/ir

There's a special fallback for the Python kernel: if it doesn't find a real kernelspec, but it can import the ipykernel package, it provides a kernel which will run in the same Python environment as the notebook server. A path ending in ipykernel/resources, like in the example above, is this default kernel. The default often does what you want, so if the python3 kernelspec points somewhere else and you can't start a Python kernel, try deleting or renaming that kernelspec folder to expose the default.

If your problem is with another kernel, not the Python one we maintain, you may need to look for support about that kernel.

Asking for help

As with any problem, try searching to see if someone has already found an answer. If you can't find an existing answer, you can ask questions at:

• The jupyter-notebook tag on Stackoverflow
• The jupyter/help repository on Github
• Or in an issue on another repository, if it's clear which component is responsible.

Don't forget to provide details. What error messages do you see? What platform are you on? How did you install Jupyter? What have you tried already? The jupyter troubleshoot command collects a lot of information about your installation, which can be useful.

Remember that it's not anyone's job to help you. We want Jupyter to work for you, but we can't always help everyone individually.