Install & Compatibility
Where this runs
tested against v6.11.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
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.5s · import 0.000s · 279MB
276MB installed
● package 276MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
QApplication
✓ from PyQt6.QtWidgets import QApplication
QWidget
✓ from PyQt6.QtWidgets import QWidget
QLabel
✓ from PyQt6.QtWidgets import QLabel
QVBoxLayout
✓ from PyQt6.QtWidgets import QVBoxLayout
Qt
✓ from PyQt6.QtCore import Qt
✗ from PyQt6.QtWidgets import Qt
While some Qt enums were accessible via QtWidgets in PyQt5, PyQt6 enforces stricter module separation. Core enums like AlignmentFlag are in QtCore.
This quickstart creates a simple desktop application window with a 'Hello, PyQt6!' label centered within it. It demonstrates the basic structure of a PyQt6 application, including `QApplication` instantiation, creating a `QWidget`, using a layout, and running the event loop.
import sys
from PyQt6.QtWidgets import QApplication, QWidget, QLabel, QVBoxLayout
from PyQt6.QtCore import Qt
class MyWindow(QWidget):
def __init__(self):
super().__init__()
self.setWindowTitle("My PyQt6 App")
self.setGeometry(100, 100, 400, 200)
layout = QVBoxLayout()
label = QLabel("Hello, PyQt6!", self)
label.setAlignment(Qt.AlignmentFlag.AlignCenter)
layout.addWidget(label)
self.setLayout(layout)
if __name__ == "__main__":
app = QApplication(sys.argv)
window = MyWindow()
window.show()
sys.exit(app.exec())
Debug
Known issues
breakingEnum values (like `Qt.AlignRight`) must now be accessed via explicit enum types (e.g., `Qt.AlignmentFlag.AlignRight`, `Qt.ItemFlag.Selectable`). Direct access via `Qt.` is deprecated or removed in PyQt6.fixUpdate all enum references to use the specific enum class (e.g., `Qt.AlignmentFlag.AlignCenter` instead of `Qt.AlignCenter`). Refer to the PyQt6 documentation for the correct enum types.
affects: 6.0.0 onwards (when migrating from PyQt5)
breakingThe `QApplication` instance must be a singleton. Attempting to create a second `QApplication` will raise a `RuntimeError` (`RuntimeError: Application.instance() must be called before QApplication constructor`).fixEnsure `QApplication` is instantiated only once. In test environments or complex applications, check for an existing instance using `QApplication.instance()` before creating a new one: `app = QApplication.instance() or QApplication(sys.argv)`.
affects: All PyQt6 versions
gotchaPerforming long-running or blocking operations directly on the main GUI thread will freeze your application's user interface, making it unresponsive.fixOffload intensive computations or I/O operations to separate threads using `QThread` or Python's `threading`/`multiprocessing` modules. Use Qt's signal/slot mechanism to communicate results back to the GUI thread for UI updates.
affects: All PyQt6 versions
gotchaPyQt6 (Qt) objects have a parent-child ownership model. If an object has a parent, it is automatically deleted when its parent is deleted. Misunderstanding this can lead to memory leaks (orphaned objects without parents) or premature object deletion.fixAlways assign a parent to widgets where appropriate (e.g., `QLabel('Text', parent=self)`). For objects without a parent, explicitly manage their lifecycle or ensure they are properly referenced to prevent Python's garbage collector from deleting them prematurely if they are still needed by Qt. affects: All PyQt6 versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'PyQt6'
The base PyQt6 library has not been installed in your Python environment.
fixInstall the PyQt6 package using pip: `pip install PyQt6`
ModuleNotFoundError: No module named 'PyQt6.QtWebEngineWidgets'
Specific optional PyQt6 modules (like WebEngine, Charts, Multimedia) need to be installed separately, even if `PyQt6` is already installed.
fixInstall the specific missing submodule. For QtWebEngineWidgets, use: `pip install PyQt6-WebEngine` (adjust for other modules like `PyQt6-Charts` or `PyQt6-Multimedia`).
TypeError: argument 1 has unexpected type 'NoneType'
This usually occurs when connecting a signal to a slot function that has been called immediately (e.g., `self.button.clicked.connect(self.my_method())`) instead of passing a reference to the function (`self.button.clicked.connect(self.my_method)`). The function call returns `None`, which is then incorrectly passed to the `connect` method.
fixRemove the parentheses when connecting a slot to pass a reference to the method: `self.button.clicked.connect(self.my_method)`
RuntimeError: QApplication: No instance found.
You are attempting to create or interact with PyQt6 GUI widgets or elements before a `QApplication` instance has been created and initialized.
fixEnsure that `app = QApplication(sys.argv)` is called at the very beginning of your PyQt6 application's execution, typically before any other GUI objects are instantiated.
Upgrade
Version history
6.11.0latest on PyPI · released Mar 30, 2026
Audit
Dependencies
No dependency data recorded yet.