Troubleshooting (WIP)

TODO:

• Review https://github.com/microsoft/vscode-jupyter/wiki/FAQ---(Frequently-Asked-Questions)

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

We're sorry you're having trouble and looking for a solution here. Jupyter is a vast ecosystem, and getting things working in Jupyter can be challenging primarily due to the number of libraries, tools, frameworks involved. That being said sometimes its as simple as merely installing a missing package. 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, try the pre-release version of the Jupyter extension.
• Verify the issue does not exist in Jupyter Notebook/Lab. If it does, then please review the environment or the packages used, and file an issue on the appropriate repo or the like.
• 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.
• Consider using conda when installing ML/AI specific packages. Based on our experience we've found Conda Environments to be one of the most reliable ways to get Python packages installed.
• 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, please do 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.
• Confirm this same kernel can be found in Jupyter Lab/Notebook. If the kernel cannot be found in either one of these, then its unlikely to be found in VS Code. You might want to refer to the documentation related to the installation of 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
• Outdated version of IPython
• Outdated version of IPyKernel
• Failure to start kernel due to missing package pip
• 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
• Module not installed
• Failure to import modules
• Dll load failures
• Errors with Win32api module
• Errors with pyzmq module
• Kernels fail to start as ports are blocked

Known issues

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)

Cannot connect to a remote kernel

• Verify

General execution failures

• Python packages do not load
  • Verify the python package has been installed.
  • Verify the python package can be loaded in the REPL.
  • Verify the right kernel (Python environment) has been used to run the notebook.
  • 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.
• 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.
  • 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.
  • 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.
  • 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.
• Built in modules overridden by user code