SuperQT

0.8.1 · active · verified Thu Apr 16

SuperQT is a collection of missing widgets and components that extend the capabilities of PyQt and PySide for building rich graphical user interfaces. It provides a variety of useful classes, from advanced sliders and combo boxes to utility functions for array conversion and signal blocking. The current version is 0.8.1, with frequent minor releases to add features and fix bugs, typically on a monthly basis.

Common errors

```
ModuleNotFoundError: No module named 'PyQt6'
```
cause A required Qt binding (PyQt6, PySide6, or PyQt5) was not installed.

fix Install a Qt binding, e.g., `pip install PyQt6` or `pip install PySide6`.
```
AttributeError: module 'superqt' has no attribute 'QLabeledSlider'
```
cause Attempted to import a superqt widget directly from the top-level `superqt` module instead of its specific submodule.

fix Import the widget from its correct submodule, e.g., `from superqt.sliders import QLabeledSlider`.
```
TypeError: 'builtin_function_or_method' object is not subscriptable (when using QRangeSlider)
```
cause In older versions, `QRangeSlider` might have had issues with direct tuple assignment for `setRange` or `setValue`.

fix Ensure you are on a recent version of superqt (>=0.7.7 fixed some range slider issues) and explicitly pass two arguments to `setRange(min, max)` and `setValue(min_val, max_val)`.

Warnings

breaking SuperQT v0.8.0 dropped support for Python 3.9 and PySide2. Users on these versions must upgrade their Python environment or switch to a different Qt binding like PyQt5, PyQt6, or PySide6.
Fix: Upgrade Python to 3.10+ and install a compatible Qt backend (e.g., `pip install PyQt6`).
gotcha SuperQT does NOT install a Qt binding for you. You must explicitly install one (e.g., PyQt6, PySide6, PyQt5) for superqt to function.
Fix: Install a Qt backend package alongside superqt: `pip install superqt PyQt6` (or PySide6/PyQt5).
gotcha Many superqt components are organized into specific submodules (e.g., `superqt.sliders`, `superqt.widgets`, `superqt.combobox`). Importing directly from `superqt` will often result in an `AttributeError`.
Fix: Always check the documentation or examples for the correct submodule path for the specific widget or utility you intend to use. For example, `from superqt.sliders import QLabeledSlider`.

Install

pip install superqt PyQt6 Install with PyQt6 backend (recommended)
pip install superqt PySide6 Install with PySide6 backend
pip install superqt PyQt5 Install with PyQt5 backend

Imports

QLabeledSlider
wrong:
```
from superqt import QLabeledSlider
```
correct:
```
from superqt.sliders import QLabeledSlider
```
Most superqt widgets are in specific submodules, not directly under `superqt`.
QToggleSwitch
wrong:
```
from superqt import QToggleSwitch
```
correct:
```
from superqt.widgets import QToggleSwitch
```
Widgets like QToggleSwitch are found in the `superqt.widgets` submodule.
QSearchableComboBox
wrong:
```
from superqt import QSearchableComboBox
```
correct:
```
from superqt.combobox import QSearchableComboBox
```
ComboBoxes are located in the `superqt.combobox` submodule.

qt_signals_blocked

from superqt.utils import qt_signals_blocked

Quickstart

This example demonstrates a basic `QLabeledSlider` from `superqt`, which provides a slider with an integrated label showing its current value. It requires a Qt application context.

import sys
from superqt.sliders import QLabeledSlider
from PyQt6.QtWidgets import QApplication, QWidget, QVBoxLayout

if __name__ == '__main__':
    app = QApplication(sys.argv)
    w = QWidget()
    layout = QVBoxLayout()
    
    slider = QLabeledSlider()
    slider.setRange(0, 100)
    slider.setValue(50)
    
    layout.addWidget(slider)
    w.setLayout(layout)
    w.setWindowTitle("SuperQT Labeled Slider Example")
    w.show()
    sys.exit(app.exec())

view raw JSON →