Jupyter fails to start#

• Have youinstalled it? ;-)

• If you’re using a menu shortcut or Anaconda launcher to start it, tryopening a terminal or command prompt and running the commandjupyternotebook.

• If it can’t findjupyter,you may need to configure yourPATH 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 findnotebook,check with pip or conda that thenotebook package is installed.

• Try runningjupyter-notebook (with a hyphen). This should normally be thesame asjupyternotebook (with a space), but if there’s any difference,the version with the hyphen is the ‘real’ launcher, and the other one wrapsthat.

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

• 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 betweenlocalhost and127.0.0.1.They should be the same, but in some cases it makes a difference.

Jupyter can’t start a kernel#

Files calledkernel specs tell Jupyter how to start different kinds of kernels.To see where these are on your system, runjupyterkernelspeclist:

$ jupyter kernelspec listAvailable 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 theipykernel package,it provides a kernel which will run in the same Python environment as the notebook server.A path ending inipykernel/resources, like in the example above,is this default kernel.The default often does what you want,so if thepython3 kernelspec points somewhere elseand 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.

Python Environments#

Multiple python environments, whether based on Anaconda or Python Virtual environments,are often the source of reported issues. In many cases, these issues stem from theNotebook server running in one environment, while the kernel and/or its resources,derive from another environment. Indicators of this scenario include:

• import statements within code cells producingImportError orModuleNotFound exceptions.

• General kernel startup failures exhibited by nothing happening when attemptingto execute a cell.

In these situations, take a close look at your environment structure and ensure allpackages required by your notebook’s code are installed in the correct environment.If you need to run the kernel from different environments than your Notebookserver, check outIPython’s documentationfor using kernels from different environments as this is the recommended approach.Anaconda’snb_conda_kernelspackage might also be an option for you in these scenarios.

Another thing to check is thekernel.json file that will be located in theaforementionedkernel specs directory identified by runningjupyterkernelspeclist.This file will contain anargv stanza that includes the actual command to runwhen launching the kernel. Oftentimes, when reinstalling python environments, a previouskernel.json will reference an python executable from an old or non-existent location.As a result, it’s always a good idea when encountering kernel startup issues to validatetheargv stanza to ensure all file references exist and are appropriate.

Windows Systems#

Although Jupyter Notebook is primarily developed on the various flavors of the Unixoperating system it also supports MicrosoftWindows - which introduces its own set of commonly encountered issues,particularly in the areas of security, process management and lower-level libraries.

This Worked An Hour Ago#

The Jupyter stack is very complex and rightfully so, there’s a lot going on. On occasionyou might find the system working perfectly well, then, suddenly, you can’t get past acertain cell due toimport failures. In these situations, it’s best to ask yourselfif any new python files were added to your notebook development area.

These issues are usually evident by carefully analyzing the traceback produced inthe notebook error or the Notebook server’s command window. In these cases, you’ll typicallyfind the Python kernel code (fromIPython andipykernel) performingits importsand notice a file from your Notebook development error included in that traceback followedby anAttributeError:

File"C:\Users\jovyan\anaconda3\lib\site-packages\ipykernel\connect.py",line13,infromIPython.core.profiledirimportProfileDirFile"C:\Users\jovyan\anaconda3\lib\site-packages\IPython_init.py",line55,infrom.core.applicationimportApplication...File"C:\Users\jovyan\anaconda3\lib\site-packages\ipython_genutils\path.py",line13,inimportrandomFile"C:\Users\jovyan\Desktop\Notebooks\random.py",line4,inrand_set=random.sample(english_words_lower_set,12)AttributeError:module'random'hasnoattribute'sample'

What has happened is that you have named a file that conflicts with an installed packagethat is used by the kernel software and now introduces a conflict preventing thekernel’s startup.

Resolution: You’ll need to rename your file. A best practice would be to prefix ornamespace your files so as not to conflict with any python package.

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:

• TheJupyter Discourse Forum

• Thejupyter-notebook tag on Stackoverflow

• Peruse thejupyter/help repository on Github (read-only)

• Or in an issue on another repository, if it’s clear which component isresponsible. Typical repositories include:

  • jupyter_core -secure_write()and file path issues

  • jupyter_client - kernel managementissues found in Notebook server’s command window.

  • IPython andipykernel - kernel runtime issuestypically found in Notebook server’s command window and/or Notebook cell execution.