Install & Compatibility
Where this runs
tested against v5.15.2.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.8s · import 0.000s · 467MB
459MB installed
● package 459MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
QApplication, QWidget
✓ from PySide2.QtWidgets import QApplication, QWidget
✗ from PySide6.QtWidgets import QApplication, QWidget
When migrating from PySide2, the import paths change from PySide2 to PySide6.
QtCore, QtGui, QtWidgets
✓ from PySide2 import QtCore, QtGui, QtWidgets
✗ from PySide2.QtWidgets import *
Avoid wildcard imports to keep the namespace clean and prevent potential conflicts.
This quickstart code creates a basic PySide2 application that displays a window with a 'Hello, PySide2 World!' label. It demonstrates the fundamental steps: creating a QApplication instance, a QWidget as the main window, adding a QLabel, and starting the application's event loop using `app.exec_()` to keep the window open.
import sys
from PySide2.QtWidgets import QApplication, QWidget, QLabel
if __name__ == '__main__':
app = QApplication(sys.argv)
# Create a Qt widget, which will be our window.
window = QWidget()
window.setWindowTitle('Hello PySide2')
window.setGeometry(100, 100, 280, 80)
# Create a label and set its text
label = QLabel('Hello, PySide2 World!', parent=window)
label.move(60, 30)
window.show() # IMPORTANT!!!!! Windows are hidden by default.
sys.exit(app.exec_()) # Start the event loop.
Debug
Known issues
breakingWhen migrating to PySide6 (Qt6), many modules and function signatures have changed. For example, `QAction` moved from `QtWidgets` to `QtGui`, `QDesktopWidget` was removed (use `QScreen`), `QFontMetrics.width()` became `horizontalAdvance()`, and `QRegExp` was replaced by `QRegularExpression`.fixConsult the 'Porting Applications from PySide2 to PySide6' guide in the official Qt for Python documentation. Update import statements and method calls accordingly.
affects: All PySide2 versions when porting to PySide6
gotchaQObjects in PySide2 (and Qt in general) are C++ objects managed by Qt's memory management. If a Python reference to a QObject falls out of scope, the underlying C++ object may be prematurely deleted, leading to crashes or unexpected behavior.fixEnsure QObjects that need to persist have a strong Python reference (e.g., as an attribute of another long-lived object) or are parented to another QObject in the constructor, which transfers ownership.
affects: All PySide2 versions
gotchaRunning PySide2 applications within IDEs that themselves use a Qt backend (like Spyder or Jupyter Notebook's kernel) can lead to conflicts, such as `QApplication` instance errors or import failures, because the IDE might have already loaded its own Qt bindings (e.g., PyQt5).fixRun PySide2 applications from a standard Python interpreter in a terminal, or configure your IDE to run scripts in a dedicated external process. For Spyder, setting the `QT_API` environment variable to `'pyside2'` might help, but running externally is generally more reliable.
affects: All PySide2 versions, specific to certain IDEs
deprecatedThe `exec_()` method for starting the event loop (e.g., `app.exec_()`) includes an underscore for Python 2.x compatibility (where `exec` was a keyword). In Python 3 and PySide6, the underscore is removed, and `exec()` is preferred. While `exec_()` still works in PySide2 with Python 3, using `exec()` might become a habit that breaks in PySide2 if not careful.fixFor PySide2, continue using `app.exec_()`. Be aware that if you look at PySide6 examples or official Qt documentation for Qt6, you will see `app.exec()` instead.
affects: All PySide2 versions (when migrating to PySide6)
Errors
Common errors & fixes
ImportError: DLL load failed: The specified procedure could not be found.
Missing C++ runtime dependencies (e.g., Visual C++ Redistributable on Windows) or a Python version incompatibility with the installed PySide2 wheels.
fixEnsure the correct Visual C++ Redistributable for your system is installed. Verify your Python version against the PySide2 wheels available on PyPI (check the 'Download files' section for compatible Python versions).
Could not find a version that satisfies the requirement pyside2 (from versions: none) No matching distribution found for pyside2
Your Python version does not have pre-built PySide2 wheels available on PyPI. This often happens with newer Python versions (e.g., Python 3.11+ for PySide2 5.15.x).
fixUse a Python version explicitly supported by PySide2 (e.g., Python 3.5-3.10 for PySide2 5.15.x). Consider using virtual environments to manage different Python versions or upgrade to PySide6 if a newer Python version is essential.
RuntimeError: You need one (and only one) QApplication instance per application.
Attempting to create multiple `QApplication` instances within a single Python process. This often occurs in interactive environments (like `ipython` or certain IDEs) or when re-running GUI code without restarting the interpreter.
fixEnsure `QApplication` is instantiated only once. For interactive use, restart your Python interpreter or run your GUI script as a standalone process. You can check for an existing instance with `QApplication.instance()` before creating a new one.
Segmentation fault when importing PySide2 or running PySide2 applications.
Memory access issues, often related to deep incompatibilities between PySide2's C++ bindings and specific Python versions (e.g., Python 3.12 has known issues), or environmental conflicts.
fixUse a Python version officially supported by PySide2. If the issue persists, try reinstalling PySide2 in a clean virtual environment. Check system logs for more details on the segmentation fault.
Upgrade
Version history
5.15.2.1latest on PyPI · released Jan 14, 2022
Audit
Dependencies
No dependency data recorded yet.