{"id":9236,"library":"pyside2","title":"PySide2","description":"PySide2 provides the official Python bindings for the Qt cross-platform application and UI framework, specifically for Qt5. It enables Python developers to create robust desktop graphical user interfaces. As of version 5.15.2.1, PySide2 is primarily in maintenance mode, with active development having shifted to PySide6 for Qt6. Releases are less frequent now compared to PySide6.","status":"maintenance","version":"5.15.2.1","language":"en","source_language":"en","source_url":"https://wiki.qt.io/Qt_for_Python","tags":["GUI","Qt","desktop","bindings","UI","Qt5"],"install":[{"cmd":"pip install pyside2","lang":"bash","label":"Install latest PySide2"}],"dependencies":[],"imports":[{"note":"When migrating from PySide2, the import paths change from PySide2 to PySide6.","wrong":"from PySide6.QtWidgets import QApplication, QWidget","symbol":"QApplication, QWidget","correct":"from PySide2.QtWidgets import QApplication, QWidget"},{"note":"Avoid wildcard imports to keep the namespace clean and prevent potential conflicts.","wrong":"from PySide2.QtWidgets import *","symbol":"QtCore, QtGui, QtWidgets","correct":"from PySide2 import QtCore, QtGui, QtWidgets"}],"quickstart":{"code":"import sys\nfrom PySide2.QtWidgets import QApplication, QWidget, QLabel\n\nif __name__ == '__main__':\n    app = QApplication(sys.argv)\n\n    # Create a Qt widget, which will be our window.\n    window = QWidget()\n    window.setWindowTitle('Hello PySide2')\n    window.setGeometry(100, 100, 280, 80)\n\n    # Create a label and set its text\n    label = QLabel('Hello, PySide2 World!', parent=window)\n    label.move(60, 30)\n\n    window.show()  # IMPORTANT!!!!! Windows are hidden by default.\n\n    sys.exit(app.exec_()) # Start the event loop.","lang":"python","description":"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."},"warnings":[{"fix":"Consult the 'Porting Applications from PySide2 to PySide6' guide in the official Qt for Python documentation. Update import statements and method calls accordingly.","message":"When 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`.","severity":"breaking","affected_versions":"All PySide2 versions when porting to PySide6"},{"fix":"Ensure 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.","message":"QObjects 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.","severity":"gotcha","affected_versions":"All PySide2 versions"},{"fix":"Run 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.","message":"Running 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).","severity":"gotcha","affected_versions":"All PySide2 versions, specific to certain IDEs"},{"fix":"For 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.","message":"The `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.","severity":"deprecated","affected_versions":"All PySide2 versions (when migrating to PySide6)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure 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).","cause":"Missing C++ runtime dependencies (e.g., Visual C++ Redistributable on Windows) or a Python version incompatibility with the installed PySide2 wheels.","error":"ImportError: DLL load failed: The specified procedure could not be found."},{"fix":"Use 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.","cause":"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).","error":"Could not find a version that satisfies the requirement pyside2 (from versions: none) No matching distribution found for pyside2"},{"fix":"Ensure `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.","cause":"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.","error":"RuntimeError: You need one (and only one) QApplication instance per application."},{"fix":"Use 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.","cause":"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.","error":"Segmentation fault when importing PySide2 or running PySide2 applications."}]}