Troubleshooting (WIP)

TODO:

• Review https://github.com/microsoft/vscode-jupyter/wiki/FAQ---(Frequently-Asked-Questions) TODO:
• Kernel doctor use IPython console to replicate issues

What to do when things don't work as expected?

We're sorry you're having trouble and looking for a solution here. This document tries to help users get unblocked when running into issues.
Hopefully the following simple checklist would suffice:

• Verify you are on the latest version of VS Code and Jupyter extension.
• The issue may have already been fixed, please consider trying the pre-release version of the Jupyter extension.
• Try updating the packages to the latest version. If this isn't possible try creating a new environment (virtual environment or a Conda environment) and try again.
• Verify you are not using an outdated/unsupported version of Python (see here https://endoflife.date/python)
• Please review some of the below sections to try and get the issue resolved.

If all else fails, consider Ask question on the discussion channel or file an issue and we'd be happy to help you get unblocked.

Cannot find my kernel

• Confirm the Python extension has been installed when working with Python kernels.
• If the Python Environment cannot be found in the list of kernels, verify this is listed in the list of Python Interpreters you get when you select the command Python: Select Interpreter. If the Python environment in question is not listed in there either, then its unlikely to be listed in the list of Kernels. Please file an issue against the Python extension here and we'll be happy to look into this issue and get you unblocked.

Cannot start a kernel (cannot run a single cell)

• IPyKernel and other dependencies are not installed
• Module not installed
• Failure to import modules
• Dll load failures
• Errors with Win32api module
• Errors with pyzmq module
• Outdated version of IPython
• Failure to start kernel when using Conda Environments
• ipykernel & other dependencies are installed, yet I am asked to install these dependencies
• Built in modules overridden by user code
• Kernels fail to start as ports are blocked
• Outdated version of IPyKernel
• Failure to start kernel due to missing package pip

Known issues (move to corresponding discussion items)

For a full list of all known issues, please see the list of issues here.
Please up-vote these issues to help us prioritize getting these addressed.

• The OCAML kernel does not work (#8897)

• Kernels using 32-bit Python environments installed via conda does not work (#9134)

• xeus Python kernel is currently not supported (hence hidden) (#5469)

• I cannot run any cell (link)

• I can run some cells (link)

• I cannot find my kernel (link)

General execution failures

• Python packages do not load
  • Verify the python package has been installed ... shell/python commands
  • Verify the python package can be loaded in the REPL ... shell/python commands
  • Verify the right kernel (Python environment) has been used to run the notebook. ... import sys... sys.executable
• Kernel crashes when running some code
  • Verify you do not have any python files that could potentially override built-in modules such as os.py, random.py, email.py, and the like. .. what are built in modules, how to find them, and what to do.
  • Verify the kernel does not always crash, and only crashes when running a specific cell or using a specific kernel. This helps narrow down the issue to a specific package or environment.
  • It has been observed that some packages (such as tensorflow) if incorrectly installed or found to be outdated, can result in the kernel crashing. .. instructions to properly install tensorflow
  • Please verify the same code runs successfully in Jupyter Notebooks or Jupyter Lab. If it fails there too, please consider updating the packages to the latest versions or filing an issue against the corresponding repo or the like. .. instructions for installing jupyter and testing the output..
  • Review the output in the Jupyter output panel to understand why the kernel may have crashed. The logs generally point to a Python package that caused the kernel to crash. ... instructions for jupyter output panel & how to get to it..
• Built in modules overridden by user code .. Remove this, but ensure the target page has details on what user needs to do