TROUBLESHOOTING.md

Spyder Troubleshooting Guide

For an up to date, more comprehensive version of this guide, covering solutions to specific commonly reported issues along with these more general troubleshooting strategies, please refer to https://github.com/spyder-ide/spyder/wiki/Troubleshooting-Guide-and-FAQ Thanks, and best of luck!

Trouble with Spyder? Read this first!

If Spyder crashes or you receive an error message, please read the following troubleshooting steps before opening a new ticket. There's a good chance that someone else has already experienced the same issue, so solving it yourself will likely get Spyder working again for you as quickly as possible.

Important Note: To make sure you're getting the most relevant help for your problem, please make sure the issue is actually related to Spyder:

• If the problem appears to be a result of your own code, Stack Overflow https://stackoverflow.com/ is a better place to start;
• If the bug also occurs in the standard python, IPython, or qtconsole environments, or only with a specific package, it is unlikely to be something in Spyder, and you should report it to those sources instead.
• If the problem lies with your specific install, uninstalling and clean- reinstalling the Anaconda distribution from https://www.anaconda.com/download/ is strongly recommended. As the other methods of installing Spyder have many pitfalls for the unwary, we generally aren't able to give individual support for install issues.

Just like the programs you code in it, Spyder is written in Python, so you can often figure out many a problem just by reading the last line of the traceback or error message from the error dialog or Spyder's internal console, the latter available from Panels > Internal Console under the View menu. Oftentimes, that alone will tell you how to fix the problem on your own, but if not, we're here to help.

If you check out our list of issue categories and problem descriptions and see a question, error message or traceback that looks familiar, the relevant sub-section will likely be of the most specific help solving your issue as quickly as possible. If those steps don't work, or you can't find a similar problem, you can try some Basic First Aid (next section) or, if Spyder won't launch, some Emergency CPR (section after) and see if that clears it up.

Finally, if you still can't get it to work, and the problem is indeed Spyder-related (see above note), you should consult the the Calling for Help section for other resources to explore and details on how to submit an issue to our Github tracker, so the problem can be fixed for everyone. Thanks for taking the team to read this, and best of luck!

Basic First Aid: General troubleshooting

These suggestions, while more of a shotgun approach, tend to fix the majority of reported issues just on their own. In the rough order you should try them:

Recommended troubleshooting steps

• Restart Spyder, and try what you were doing before again.
• Upgrade Spyder to the latest release, and you might find your issue is resolved (along with new features, enhancements, and other bug fixes). Minor releases come out every two months, so unless you've updated recently, there is a good chance your version isn't the latest; you can find out with the Check for updates command under the Help menu. To perform the update with conda (strongly recommended), just run conda update spyder from the Anaconda Prompt/Terminal/command line (on Windows/Mac/Linux).
• Update Spyder's dependencies and environment, either by installing the latest version of your distribution (e.g. the recommended Anaconda), or with the relevant "update all" command in the Anaconda Prompt/Terminal/ command line (on Windows/Mac/Linux). Using conda, you can run conda update anaconda to get the latest stable version of everything.
• Restart your machine, in case the problem lies with a lingering process or another such issue.
• From the Anaconda Prompt/Terminal/command line (on Windows/Mac/Linux), run the command spyder --reset, which will restore Spyder's config files to their defaults, which solves a huge variety of Spyder issues. Note: This will reset your preferences, as well as any custom keyboard shortcuts or syntax highlighting schemes, so you should back up the .spyder-py3 folder in your user home directory if you particularly care about any of those, so you can restore them should this not solve the problem.
• Try installing Spyder into a new conda environment (recommended) or virtualenv, and only installing its dependencies there, and seeing if the issue reoccurs. If it does not, it is likely due to another package installed on your system, particularly if done with pip, which can cause many problems and should be avoided if at all possible.
• If none of these solve your issue, you should do a full uninstall of Spyder by whatever means you originally installed it, and then do a clean install of the latest version of the Anaconda distribution https://www.anaconda.com/download/, which is how we recommend you install Spyder and keep in up to date. While you are welcome to get Spyder working on your own by one of the many other means we offer, we are only able to provide individual support for install-related issues for users of the Anaconda distribution. In particular, pip installation, while doable, is only really for experts, as there are many pitfalls involved and different issues specific to your setup, which is why we recommend using conda whenever possible.

Standard approach to isolating problems

If you get the error while running a specific line, block, or script/program, it may not be an issue with Spyder, but rather something lower down in the "stack" it depends on. Try running it in the following, in order, if and until it starts working as you expect, and report the bug, if there is one, to the last one it doesn't work in.

1. Spyder, of course! Make sure you can reproduce the error, if possible.
2. A bare qtconsole instance, e.g. launched from Anaconda navigator or from the Anaconda Prompt/Terminal/command line (Windows/Mac/Linux) with jupyter qtconsole. qtconsole is the GUI console backend Spyder depends on to run its code, so most issues involving Spyder's Console are actually something with qtconsole instead, and can be reported to their issue tracker: https://github.com/jupyter/qtconsole/issues/
3. An IPython command line shell, launched with e.g. ipython from the Anaconda Prompt/Terminal/command line (Windows/Mac/Linux). Reproducable bugs can be reported to their Github page, though make sure to read thier guidelines and docs first: https://github.com/ipython/ipython/issues
4. A stock Python interpreter, either run as a script file with python path/to/your/file.py or launched interactively with python, from your Anaconda Prompt/Terminal/command line (Windows/Mac/Linux). While its not impossible it is a Python bug, t much more likely to be an issue with the code itself or a package you are using, or else a fundamental behavior, design choice or limitation of the Python language that likely won't be fixed anytime soon, so your best sources are the Python docs: https://www.python.org/doc/, and the other resources listed above.

Remember, if the problem reoccurs in a similar or identical way with any of these methods (other than only Spyder itself), then it is almost certainly not an issue with Spyder, and would be best handled elsewhere. As as we aren't able to do much of anything about issues not related to Spyder, a forum like Stack Overflow https://stackoverflow.com/ or the relevant package's docs is a much better place to get help or report the issue in that case; see the Emergency Numbers section near the end of the document for other places to look for information and assistance. Best of luck!

Emergency CPR: Spyder won't launch

Just like in the real world, while it may be scary or disconcerting to have Spyder not come to life for you, these situations are almost always fixable so long as you stay calm, keep a cool head, and carefully follow the steps above and below.

Common solutions

• The basic troubleshooting steps discussed in the section above, as they usually resolve the vast majority of Spyder install-related issues.
• Make sure Spyder isn't already running and no Spyder related windows (e.g. Variable Explorer dialogs) are left open, and check that the preference setting "Use a single instance" (under Preferences > General > Advanced Settings) isn't checked.
• Try starting Spyder via a different means, such as from a shortcut, Anaconda navigator, or the Anaconda Prompt/Terminal/command line (on Windows/Mac/Linux) by simply typing spyder then enter/return, and see if any of those work. If so, then something's wrong with your install, not Spyder itself, and so we recommend uninstalling and doing a clean install of the latest Anaconda https://www.anaconda.com/download/.
• If Anaconda is currently installed "for just you", try uninstalling and reinstalling it "for all users" instead, and vice versa, as some systems can have issues with one or the other.
• Reinstall it into your local startup drive, to a directory path and user account without spaces, special characters, or unusual permissions.
• Disable any security software you may be using, such as a firewall or antivirus, as these products can occasionally interfere with Spyder or its related packages. Make sure to re-enable it if it doesn't fix the problem, and if it does, add a rule or exception for Spyder.
• Run Spyder with administrator rights just in case it is some sort of permissions issue
• Check and repair/reset permissions, your disk, and OS if all else fails

Trickier tricks

If none of the above solves the problem, you can try starting Spyder directly from its Python source files which may either get it running, or at least provide very useful information to help debug the problem further. The procedure is described on, e.g., this Github issue spyder-ide#6023 (comment), which allowed the user to solve a seemingly difficult situation.

The technique essentially boils down to starting Spyder from the Anaconda Prompt/Terminal/command line (on Windows/Mac/Linux) by manually running the Spyder startup routine, start.py, with a known good Python interpreter, and observing the results. To do so, you'll need to navigate to the Spyder app directory from the command line, the location of which varies depending on how you installed it.

With Anaconda, the distribution we recommend, you can find the location(s) of your packages directory(s) with the command conda info, where the directory you want is listed under package cache. For a systemwide Anaconda install, it is usually Anaconda3/pkgs at the root of your drive, while it varies depending on your operating system for a per-user install. If both are shown, you'll need to remember how you first installed Spyder with Anaconda, or just check both. Inside the Anaconda directory, you should find the directory you're looking for under spyder-3.#.#-py##_#/Lib/site-packages/spyder/app, where the #s correspond to the most recent version present.

If using pip, which we don't officially support, you can typically find the needed directory, from the root of your drive, under /Python##/Lib/site-packages/spyder/app.

In case you're unfamiliar, you can change directories with the cd command followed by the name of the directory you'd like to navigate to. Once inside the app directory, run python start.py to launch Spyder. If it doesn't launch, then you should see an error traceback printed; carefully copy that for future reference and also run python mainwindow.py, and record your results as well.

In case the command window disappears immediately after the error on Windows, as is sometimes the case, so you cannot see what it printed just create a batch file in the app directory with with the following content::

C:/Absolute/Path/To/Your/Python/Executable/python.exe start.py

pause

which should to the trick. Replace the path with the actual path to the Python interpreter you want to use, e.g. the one with Anaconda at C:/Anaconda#/python.exe if installed for all users, or C:/Users/YOURUSERNAME/AppData/Local/conda/conda/Python#/python.exe if for just you, replacing # with the Python major version (2 or 3) of the Anaconda you downloaded. If you're unsure, you can get the correct path by entering where python in the Anaconda Prompt, and using the first path shown there. Then, just doulbe click the batch file to run it, and you should see the output you need.

If reading the output, particularly the last line, doesn't solve the problem, then record all of it carefully, and post it as part of your bug report as described under the Calling for Help seciton near the end of this document.

Advanced Treatments: Debugging and patching

If you know your way around Python, you can often diagnose and even fix or patch issues yourself. You can explore the error messages you're receiving and Spyder's inner workings with the Internal Console under the menu item View > Panes > Internal Console. If you want more detailed debug output, open an Anaconda Prompt/Terminal/command line (on Windows/Mac/Linux), set the environment variable SPYDER_DEBUG to the value "3" (on cmd, use set SPYDER_DEBUG=3; with bash, execute export SPYDER_DEBUG="3", and for tcsh, run setenv SPYDER_DEBUG 3. Then, launch Spyder from that same shell with spyder, and observe the results. Even if you don't manage to fix the problem yourself, this output can be immensely helpful in aiding us to quickly narrow down and solve your issue for you.

However, if you do feel up to it and think you know where to look and what to change, you are welcome to take a stab at patching the bug. Just clone the relevant development branch of Spyder (e.g. 3.x for bug fixes) from our Github repo: https://github.com/spyder-ide/spyder/, edit the relevant Python code in your favorite editor or IDE (or Spyder itself!), and test your changes by running it from the cloned repo with python bootstrap.py from the repo's root directory (e.g. spyder). Then, commit your changes to a github branch, and submit a Pull Request to the Spyder repo for them to be included in the next main Spyder distribution!

For a quick, step by step guide to the process, see our CONTRIBUTING document on Github: https://github.com/spyder-ide/spyder/blob/master/CONTRIBUTING.md, and for even more about developing Spyder, check out our Github wiki: https://github.com/spyder-ide/spyder/wiki. Thanks for your help!

Emergency Numbers: Additional helpful resources to consult

Aside from this document, there are a number of other sources of documentation and troubleshooting information you should at least search or skim, before submitting an issue, as they might already offer an answer or at least help you better understand the following. Even if we aren't able to help you, these places might.

Spyder-related platforms

• Spyder documentation: https://docs.spyder-ide.org/ It explains how to use Spyder's basic features and addresses a number of common "How can I?" questions that arise. Its still a work in progress, so if you discover something missing from the docs, please submit an issue or pull request to add it!
• Spyder dev documentation: https://github.com/spyder-ide/spyder/wiki Along with additional general information about Spyder and its features, our wiki has information about how to develop and test Spyder, our development roadmap and the features planned in the next release, other common questions, the changelog, and much more.
• Spyder website: https://www.spyder-ide.org/ While it is still under very early alpha development and isn't polished for public consumption, it does contain basic information about Spyder and links to many other helpful resources.
• Spyder Google Group: https://groups.google.com/group/spyderlib Great for your more help-related questions, particularly those you aren't sure are a full-on Spyder issue, or you'd like to give more general feedback or ask questions of the team.
• Spyder Gitter: https://gitter.im/spyder-ide/public If you've got a quick question to ask the team and are looking for a quick answer, this is a great place to chat directly with the Spyder developers.
• Stack Overflow: https://stackoverflow.com/questions/tagged/spyder Particularly if your question is more programming related, or has more to do with something particular to your own code that you just can't get working, this is a great place to start searching and posting. It has an active Spyder community as well, with new Spyder-related questions posted every day, and the developers, especially the lead maintainer, are active in answering them.
• Spyder OpenCollective: https://opencollective.com/spyder/ If you enjoy Spyder and want to help fund us fixing bugs and adding your most requested new features, please support our work on OpenCollective!

Python help and problems

• Google/your favorite search engine: One never fails to be surprised how many problems can be solved by a simple Google search!
• Official Python Help page: https://www.python.org/about/help/ A great resource that lists a number of places you can get help, support and learning resources for the Python language and its packages.
• Python Documentation: https://www.python.org/doc/ A number of issues can be explained due to quirks in the language itself or misunderstandings as to how it behaves, and so those and much more can be found here.
• r/Python: https://www.reddit.com/r/Python/ and r/learnpython: https://www.reddit.com/r/learnpython/ The former is aimed more at general Python usage and the latter more at beginners, but both are popular places to ask about and discuss issues with Python and its packages.

Data science/SciPy resources:

• Anaconda Support: https://www.anaconda.com/support/ Offers free community help and documentation for the Anaconda applications, installing the Anaconda distribution, and using the conda package and environment manager, as well as paid support options.
• SciPy.org Website: https://www.scipy.org/ The central home of the scipy stack, with information, documentation, help, and bug tracking for many of the core packages used with Spyder, including NumPy, SciPy, Matplotlib, Pandas, Sympy, and IPython.
• Project Jupyter: https://jupyter.org/ Development hub for IPython, Spyder's qtconsole, Jupyter notebooks used with the spyder-notebook plugin, and more.
• Data Science Stack Exchange: https://datascience.stackexchange.com/ For questions that relate more to data science than programming specifically, data science stack exchange is a good place to ask and answer them.

Calling For Help: Still have a problem?

If you can't find your issue here, you're fairly sure its Spyder-related, and a full course of general troubleshooting didn't solve it, then you'll want to submit it to our issue tracker so our team can take a look at it for you. You'll need a github account to do that, so make sure you have one before you begin (a good idea anyway).

Important Note: Before you submit an issue, make sure you've searched a description of the problem, and a relevant portion of the error traceback, on both Google and the Spyder repository/Issue tracker (see above or below) to make sure it hasn't been submitted before. We currently have over 5,000 submitted issues in the past few years, along with over 1,500 stack overflow questions tagged spyder and thousands of Google Groups posts, among others, so it is quite likely your issue or problem has been reported/solved before. If that's the case, your issue will be closed your issue as a duplicate, so be sure to check first!

Ways to submit an issue

If you are able to launch Spyder, the best way to do so is to simply select Submit Issue from the Help menu or, better yet, right from the error dialog if present, which will automatically take you to the correct page; prefill an error report with your environment details, key versions and dependencies; give you a basic structure to fill in as needed; and (if the latter) automatically insert the error/traceback for you.

If Spyder won't launch (or otherwise isn't available), you can also submit a report manually at our Issues page on Github https://github.com/spyder-ide/spyder/issues. Unlike the above, you'll need to manually provide the versions of everything (Spyder, Python, OS, Qt/PyQt, Anaconda, and Spyder's dependencies) as listed in the error report template; see below for more on that.

Must-have and helpful items to include

Please include as much as possible of the following in your report to maximize your chances of getting relevant help and our ability to diagnose, reproduce and solve your issue. In particular, be sure to include the first two items, as without these we will usually be unable to isolate the problem in order to confirm and fix it, and the issue will be automatically closed after one week (7 days) if we don't hear from you.

The key items, in rough order of priority:

• The full, complete error message or traceback copy/pasted or automatically entered exactly as displayed by Spyder:

  • Auto-generated reports directly from the error dialog should include this automatically, but double check to make sure.
  • You can copy and paste this from the the "Show Details" section of the error dialog.
  • If not present, or a dialog is not displayed, you can also find it printed to Spyder's Internal Console, located under the View menu at Panels > Internal Console.
  • If you prefer, or if Spyder won't start, you can start Spyder from the Anaconda Prompt/Terminal/command line (Windows/Mac/Linux) with spyder and copy the output printed there.

  If you are reporting a specific behavior rather than an error, or the message does not fully explain what occurs, please describe in detail what actually happened, and what you expected Spyder to do.

• A detailed, step by step description of exactly what you did leading up to the error/crash/behavior occurring, complete with (minimal) code that triggers it, if possible/applicable. The more specific you are here, the easier and faster the problem can be reproduced and fixed.

• Information about Spyder and its environment, as listed in the error report template (if not already filled in automatically by Spyder, via Help > Report Issue), which you can find under About Spyder in the Help menu, along with its key dependencies, shown in the dialog under Help > Dependencies (there's a button to copy-paste them). If Spyder won't launch, you can get the Core Components information from conda or Anaconda Navigator, and paste output of conda list from Anaconda Prompt/Terminal/command line (on Windows/Mac/Linux) for the rest.

• How you installed Spyder and any other relevant packages, e.g. Anaconda/conda (highly recommended), another distribution like WinPython, through MacPorts or your distribution's package manner, using pip, manually from source, etc, and whether Spyder has worked before since you installed it. *Note that unfortunately, we generally cannot provide individual support for installation issues with methods other than conda/Anaconda.

• What else you've tried to fix it, e.g. from this guide or elsewhere on the web, whether you've seen it reported anywhere else, replicated it on multiple machines, or (if appropriate) tried to reproduce it in standalone Qtconsole, IPython, and/or the plain Python interpreter.

• Whether the problem occurred consistently before in similar situations, only some of the time, or this is the first time you've observed it, and whether it occurred the first time you tried the behavior that triggered it in a new Spyder install.

• Anything else special or unusual about your system, environment, packages, or specific usage that might have anything to do with the problem

Important note about pasting code into Github

If including block(s) of code in your report, be sure to precede and follow it with a line of three backticks ``` to get a code block like this::

Your Code Here!

Otherwise, your code will likely contain random formatting or missing indentation, making it difficult or impossible for others to examine and run to reproduce and fix your issue. Plus, it looks much nicer, too.

Next steps and thank you!

Once you submit your report, our team will try to get back to you as soon as possible, often within 24 hours or less, to try to isolate the problem on our end and help you fix/work around it on yours.

Thanks for using Spyder, and we appreciate your help making it even better!