qt-threading

Qt Threading

The Golden Rule

Never update UI widgets from a non-main thread. All widget operations must happen on the main (GUI) thread. Use signals to marshal results back from worker threads.

Pattern 1: Worker Object + QThread (preferred for stateful workers)

Move a QObject subclass to a QThread. The worker's slots execute in the thread's event loop.

from PySide6.QtCore import QObject, QThread, Signal, Slot

class DataFetcher(QObject):
    """Worker that fetches data in a background thread."""
    result_ready = Signal(dict)
    error_occurred = Signal(str)
    progress = Signal(int)
    finished = Signal()