PySide2

Common errors

• ImportError: DLL load failed: The specified procedure could not be found.

  cause Missing C++ runtime dependencies (e.g., Visual C++ Redistributable on Windows) or a Python version incompatibility with the installed PySide2 wheels.
  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).

• Could not find a version that satisfies the requirement pyside2 (from versions: none) No matching distribution found for pyside2

  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).
  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.

• RuntimeError: You need one (and only one) QApplication instance per application.

  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.
  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.

• Segmentation fault when importing PySide2 or running PySide2 applications.

  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.
  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.

Warnings

• breaking 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`.
  Fix: Consult the 'Porting Applications from PySide2 to PySide6' guide in the official Qt for Python documentation. Update import statements and method calls accordingly.
• gotcha 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.
  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.
• gotcha 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).
  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.
• deprecated 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.
  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.

Install

• pip install pyside2 Install latest PySide2

Imports

• QApplication, QWidget
  wrong:

  from PySide6.QtWidgets import QApplication, QWidget

  correct:

  from PySide2.QtWidgets import QApplication, QWidget

  When migrating from PySide2, the import paths change from PySide2 to PySide6.
• QtCore, QtGui, QtWidgets
  wrong:

  from PySide2.QtWidgets import *

  correct:

  from PySide2 import QtCore, QtGui, QtWidgets

  Avoid wildcard imports to keep the namespace clean and prevent potential conflicts.

Quickstart

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.