Install & Compatibility
Where this runs
tested against v4.5.0 · 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
677MB installed
● package 677MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
qtbot (fixture)
✓ def test_something(qtbot):
# use qtbot here
✗ from pytest_qt.plugin import qtbot # or similar
pytest-qt's primary features are exposed via fixtures, which are automatically discovered by pytest and injected into test functions. They should not be imported directly.
This quickstart demonstrates a basic test using the `qtbot` fixture. `qtbot` provides methods to interact with Qt widgets. `qtbot.addWidget` is used to manage the widget's lifecycle for the duration of the test, handling showing and cleanup. The specific `QtWidgets` import (e.g., PyQt5, PySide6) depends on your chosen Qt binding.
from PyQt5.QtWidgets import QLabel
import pytest
def test_label_text_using_qtbot(qtbot):
# The QApplication instance is managed by pytest-qt (via the 'qapp' fixture if needed).
# We typically don't create/quit QApplication explicitly in tests using pytest-qt.
label = QLabel('Hello QtBot')
qtbot.addWidget(label)
# qtbot.addWidget ensures the widget is shown and its lifecycle is managed for the test.
# No explicit label.show(), qtbot.waitExposed(), or label.close() needed for basic interaction.
assert label.text() == 'Hello QtBot'
Debug
Known issues
breakingThe environment variable `PYTEST_QT_FORCE_PYQT` for forcing PyQt API selection was deprecated in favor of `PYTEST_QT_API` in version 1.3.0. While `PYTEST_QT_FORCE_PYQT` was initially kept for backward compatibility, new projects and updated configurations should use `PYTEST_QT_API`.fixUse the `PYTEST_QT_API` environment variable (e.g., `export PYTEST_QT_API=pyqt5`) or the `qt_api` config option in `pytest.ini` to explicitly select the Qt binding (e.g., `qt_api = pyside6`).
affects: All versions, especially projects migrating from <1.3.0
gotchaPrior to `pytest-qt` version 1.5.0, exceptions raised within a `qtbot.waitSignals` or `qtbot.waitSignal` with-statement block could be swallowed and result in a `SignalTimeoutError` instead of the actual exception, masking the root cause of the failure.fixUpgrade to `pytest-qt` version 1.5.0 or later to ensure that actual exceptions are correctly propagated when using signal waiting utilities.
affects: <1.5.0
breakingWhen using `PyQt5.5` or newer, Qt changed its default behavior to call `abort` on unhandled exceptions in virtual methods during tear down, which could crash the interpreter. `pytest-qt` version 1.5.1 introduced a fix to capture these exceptions during tear down, preventing crashes.fixUpgrade to `pytest-qt` version 1.5.1 or later. It's also good practice to ensure your Qt application handles exceptions gracefully in virtual methods to prevent such issues at the Qt level.
affects: <1.5.1 when used with PyQt >= 5.5
gotchaWhile `pytest-qt` attempts to auto-detect the available Qt binding (PyQt5, PyQt6, PySide2, PySide6), explicit configuration is highly recommended to avoid unexpected behavior or conflicts if multiple bindings are installed. The order of `sys.path` and other factors can influence auto-detection.fixAlways explicitly configure the desired Qt binding using the `PYTEST_QT_API` environment variable (e.g., `PYTEST_QT_API=pyside6`) or by adding `qt_api = pyside6` to your `pytest.ini` file. This ensures consistent test execution.
affects: All versions
Upgrade
Version history
4.5.0latest on PyPI · released Jul 1, 2025
Audit
Dependencies
pytestrequiredpytest-qt is a plugin for the pytest testing framework.
PyQt5optionalOne of the Qt bindings is required to run tests against a Qt application. pytest-qt supports PyQt5, PyQt6, PySide2, and PySide6.
PyQt6optionalOne of the Qt bindings is required to run tests against a Qt application. pytest-qt supports PyQt5, PyQt6, PySide2, and PySide6.
PySide2optionalOne of the Qt bindings is required to run tests against a Qt application. pytest-qt supports PyQt5, PyQt6, PySide2, and PySide6.
PySide6optionalOne of the Qt bindings is required to run tests against a Qt application. pytest-qt supports PyQt5, PyQt6, PySide2, and PySide6.