Diagnosing and Fixing Spyder IPython Console Startup Failures

Recognizable Condition

When you open Spyder, the IPython console pane remains blank, shows an error such as "Kernel died" or "Unable to connect to kernel", or the editor works but code execution hangs with no output.

Cause/Diagnostic Table

Possible Cause	What to Look For
Missing or incompatible dependencies (ipykernel, jupyter_client)	Console error mentions kernel import failure; `pip list` shows missing packages.
Corrupted Spyder configuration or workspace	Issue persists across projects; resetting Spyder (`spyder --reset`) changes behavior.
System resources exhausted (memory/CPU)	Kernel crashes after a spike in memory/CPU usage visible in system monitor.
Conflicting environment variables (e.g., PYTHONPATH)	Unsetting the variable and restarting Spyder restores console function.

Ordered Checks

1. Verify the selected Python interpreter

   Open a terminal, activate the environment Spyder uses, and run:

   pip list | grep -E "ipykernel|jupyter_client"
   

   Ensure ipykernel>=6.0 and jupyter_client are present. If not, note the missing package.

   Where to run: any terminal with user permissions. Risk: none beyond normal package queries.

2. Launch Spyder with a clean configuration

   Run:

   spyder --reset
   

   This starts Spyder without user‑specific settings. Observe whether the console now starts.

   Permissions: user level. Risk: resets window layouts and plugins; you may need to reconfigure them later.

3. Monitor system resources while testing

   Open a system monitor (e.g., top, Task Manager). In Spyder, try to run a simple script:

   print('hello')
   

   Watch for memory or CPU spikes that coincide with the kernel failure.

   Where: terminal for monitor, Spyder IDE for script. Risk: none.

4. Temporarily unset Spyder‑related environment variables

   In the terminal before launching Spyder, execute:

   unset PYTHONPATH
   unset SPYDER_PYTHONPATH
   spyder
   

   If the console works, one of those variables was causing a conflict.

   Permissions: user. Risk: temporarily alters environment; restore by closing the terminal or re‑exporting the variables.

Fixes Tied to Findings

• Missing/incompatible dependencies: Install or upgrade the required packages in the environment Spyder uses:

pip install --upgrade ipykernel jupyter_client

• Corrupted configuration: The --reset flag already restores default settings; if you need to keep custom layouts, back up ~/.config/spyder before resetting.
• Resource exhaustion: Close unnecessary applications, increase swap space, or add physical RAM. After freeing resources, retry the simple script.
• Conflicting environment variables: Identify the offending variable (commonly PYTHONPATH) and either unset it permanently in your shell profile or adjust it to exclude paths that interfere with Spyder’s launcher.

Escalation Criteria

If the console remains unresponsive after completing all checks and applying the corresponding fixes:

1. Collect the Spyder log file: ~/.config/spyder/logs/spyder.log.
2. Capture any console traceback shown in the IDE’s status bar or in the log.
3. Note your OS, Python version (python --version), Spyder version (spyder --version), and the exact steps to reproduce.
4. Submit a report to the Spyder GitHub issue tracker with the gathered information.

Verification Steps

After applying a fix, verify that the console is responsive:

1. Run print('hello') in the IPython console and confirm the output appears.
2. Check that the Variable Explorer updates when you assign a value (e.g., x = 5).
3. Optionally, reinstall ipykernel intentionally (pip uninstall -y ipykernel) to reproduce the symptom, then reinstall it to confirm the fix resolves the issue.

Limitations

This guide covers the most common causes of console startup failure in Spyder 5.x series. Issues arising from custom plugins, third‑party kernels, or severe system‑level restrictions may require additional investigation beyond the steps described.