Fatal error: The Python kernel is unresponsive.

[Innuendo84]

I'm having problems with running databricks with cv2.

Everytime I try to import cv2 I get this error. If I comment it out error disappears.

[pradeep_singh]

See if this works - 

# 1) Clean up any non‑headless OpenCV
%pip uninstall -y opencv-python opencv-contrib-python opencv-contrib-python-headless

# 2) Install the headless package only
%pip install opencv-python-headless==4.8.1.78

# 3) Restart the Python process in this cluster
dbutils.library.restartPython()

Then in the next cell run the import .

[Innuendo84 · Accepted solution]

Thank you, it works now.

After starting a new compute following commands work:

%pip install opencv-python-headless==4.8.1.78

%pip install "numpy<2.0" (due to error: A module that was compiled using NumPy 1.x cannot be run in
NumPy 2.0.0 as it may crash.)

dbutils.library.restartPython()

Weird issue that regardless of which Databricks runtime I choose I can't use cv2, which is a popular library.

[SteveOstrowski]

Hi @Innuendo84,

Glad you got this resolved. For anyone else who runs into this, here is some additional context on why this happens and how to avoid it.

THE ROOT CAUSE

The standard opencv-python package includes GUI components (highgui, GTK/Qt bindings) that try to link against display libraries at import time. Since Databricks clusters run in a headless Linux environment with no display server, importing cv2 from the full package causes a segfault or hangs the Python process, which surfaces as the "Fatal error: The Python kernel is unresponsive" message.

THE FIX

As you discovered, install the headless variant instead:

%pip install opencv-python-headless==4.8.1.78

The headless package provides all the same image processing, video I/O, and computer vision functionality, just without the GUI window functions (like cv2.imshow), which are not usable on a cluster anyway.

NUMPY COMPATIBILITY

On newer Databricks Runtime versions that ship with NumPy 2.x, you may also need to pin NumPy to a 1.x version to avoid the "A module that was compiled using NumPy 1.x cannot be run in NumPy 2.0" crash:

%pip install "numpy<2.0"

After installing, always restart the Python interpreter so the new packages take effect:

dbutils.library.restartPython()

Then in the next cell, run your import:

import cv2

MAKING IT PERSISTENT

If you use cv2 regularly, you can avoid repeating these steps on every cluster start by using an init script or by configuring the library on your cluster's Libraries tab. You can also add these dependencies to a requirements.txt or specify them in your cluster policy or job configuration. For more details, see the documentation on cluster-scoped libraries:
https://docs.databricks.com/en/libraries/cluster-libraries.html

For notebooks, you can also place the %pip install commands in the first cell so they run automatically each time.

* This reply used an agent system I built to research and draft this response based on the wide set of documentation I have available and previous memory. I personally review the draft for any obvious issues and for monitoring system reliability and update it when I detect any drift, but there is still a small chance that something is inaccurate, especially if you are experimenting with brand new features.

If this answer resolves your question, could you mark it as "Accept as Solution"? That helps other users quickly find the correct fix.