Mac Big Sur config to open windows in Terminal with PyQt5 or PySide2?

After upgrading from macOS Catalina to Big Sur, several users found that PyQt5 and PySide2 GUI windows stopped opening when launched from Terminal or Visual Studio Code. Scripts would appear to run — the Python icon would show up in the Dock and Activity Monitor would report a Python process using 99% CPU — but no window would ever appear. The only way to stop the process was a Force Quit.

Interestingly, the same scripts worked fine when run from IDLE, and Tkinter-based GUIs had no trouble at all regardless of how they were launched.

The symptoms

The original reporter, Stephen E van Dellen, described the problem clearly:

Scripts that open a window with PyQt5 or PySide2 work as expected when started with IDLE's File, Open Module command. But if I run them with a Terminal command or in Visual Studio Code, they start OK with no indications of trouble but no window ever opens. The Python icon appears in the Dock and Activity Monitor says a Python process is running and using 99% of a CPU. I have to Force Quit it to stop it.

This happened even with the simplest possible PyQt5/PySide2 script:

from PySide2.QtWidgets import QApplication, QWidget
import sys
app = QApplication(sys.argv)
window = QWidget()
window.show()
app.exec_()

Meanwhile, a basic Tkinter script worked perfectly from Terminal:

from tkinter import Label
widget = Label(None, text='Hello GUI world!')
widget.pack()
widget.mainloop()

The environment at the time was:

• macOS Big Sur 11.0.1
• Python 3.9.0
• PyQt5 5.15.1
• PySide2 5.15.1

The solution: upgrade PyQt5 to 5.15.2

The actual fix for pip users came with the release of PyQt5 5.15.2, which resolved the Big Sur compatibility issue. To upgrade:

pip3 install --upgrade pyqt5

Or to install the specific version directly:

pip3 install pyqt5==5.15.2

Unfortunately, PySide2 5.15.2 did not fix the same problem. Stephen reported this to the Qt bug tracker at bugreports.qt.io. If you're affected and using PySide2, check for newer releases that may include the macOS Big Sur fix, or consider switching to PySide6/PyQt6 which have better support for recent macOS versions.

Summary

If you're hitting this issue and want the simplest path forward, upgrading to PyQt5 5.15.2 (or later) is the way to go. For PySide users, upgrading to PySide6 with a recent version is recommended, as both PySide2 and PyQt5 are now in maintenance-only mode and newer macOS releases will continue to cause compatibility issues with older library versions.