Notes on Qt Designer and Python UIs

Using Qt Designer

Writing the UI from Scratch

Suppose that you do not want to use Designer to create your UI. You can take the route of writing your Qt UI from scratch using Python. Again, the two offerings here, PySide and PyQt, will allow you to perform identical tasks with the Qt framework. For brevity, we will only cover PySide, though the code should effectively be the same as with PyQt.

Let’s create a file called main.py where we will place our UI. Then, we will import the following Qt widgets which are needed for our login form.

from PySide6.QtWidgets import QApplication, QWidget, QHBoxLayout, QVBoxLayout, QFormLayout, QSpacerItem, QSizePolicy, QLabel, QLineEdit, QPushButton, QMainWindow

Here’s a breakdown of what each widget does.

• QApplication allows us to use Qt’s main event loop to run our UI and handle events concurrently.
• QWidget is Qt’s base widget class.
• QHBoxLayout, QVBoxLayout, and QFormLayout are the layout managers that we will use throughout our app.
• QSpacerItem is the spacer item that we will add to the layout containing our button.
• QSizePolicy includes an enum that we will use with the spacer item.
• QLabel, QLineEdit, and QPushButton are for text labels, input fields, and push buttons respectively.
• QMainWindow is the app’s main window.

Now, we can create our main window as follows:

class MainWindow(QMainWindow):
    def __init__(self) -> None:
        super().__init__()

This class, which inherits from QMainWindow, will be the place where we will place our widgets. The super().__init__() call included here is necessary as Qt uses the init method for setup.

Because the main window itself already has an internal layout (which is used for widgets such as the menubar and toolbars), we will need to assign a central widget to our Qt window. To do this, we can create a QWidget and call self.setCentralWidget on our class.

class MainWindow(QMainWindow):
    def __init__(self) -> None:
        super().__init__()

        self.central_widget = QWidget()

        self.setCentralWidget(self.central_widget)

Our main widget will also need to have a layout so we can position elements within the widget. In the UI we made with Qt Designer, we had a vertical layout for both our login form and button. To use one here, we can create a QVBoxLayout and set it as the layout of our central widget.

class MainWindow(QMainWindow):
    def __init__(self) -> None:
        super().__init__()

        self.central_widget = QWidget()

        self.main_vbox = QVBoxLayout()

        self.central_widget.setLayout(self.main_vbox)
        self.setCentralWidget(self.central_widget)

After that, we will want to add our form layout with the corresponding fields.

class MainWindow(QMainWindow):
    def __init__(self) -> None:
        super().__init__()

        self.central_widget = QWidget()

        self.main_vbox = QVBoxLayout()

        self.form = QFormLayout()

        self.username_label = QLabel("Username")
        self.username_edit = QLineEdit()

        self.password_label = QLabel("Password")
        self.password_edit = QLineEdit()
        
        self.form.addRow(self.username_label, self.username_edit)
        self.form.addRow(self.password_label, self.password_edit)

        self.central_widget.setLayout(self.main_vbox)
        self.setCentralWidget(self.central_widget)

As you can see, we first create the layout, then the widgets that will be part of it, and then we add each field as a row using the convenient addRow method.

This gives us our form fields. However, we are still missing the login button. For this one, we will create a QHBoxLayout to house our button, a QSpacerItem to move our button to the right, and of course, our QPushButton.

class MainWindow(QMainWindow):
    def __init__(self) -> None:
        super().__init__()

        self.central_widget = QWidget()

        self.main_vbox = QVBoxLayout()

        self.form = QFormLayout()

        # ... the widgets of the form we defined earlier
        
        self.form.addRow(self.username_label, self.username_edit)
        self.form.addRow(self.password_label, self.password_edit)

        self.button_hbox = QHBoxLayout()
        
        self.spacer_item = QSpacerItem(40, 20, QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Minimum)
        self.login_button = QPushButton("Login")
        
        self.button_hbox.addItem(self.spacer_item)
        self.button_hbox.addWidget(self.login_button)

        self.central_widget.setLayout(self.main_vbox)
        self.setCentralWidget(self.central_widget)

Our button is now grouped with the spacer item in our button_hbox layout. The spacer item is defined so that it prefers a width of 40 and a height of 20 and so that it stretches or expands horizontally and shrinks down to its minimum height vertically. Because this is a spacer item, we must add it using the addItem method. To add widgets to a layout, you can use the addWidget method.

To finish our UI, we must add the two layouts to the main vertical layout using addLayout:

class MainWindow(QMainWindow):
    def __init__(self) -> None:
        super().__init__()

        self.central_widget = QWidget()

        self.main_vbox = QVBoxLayout()

        self.form = QFormLayout()

        # ... the widgets of the form we defined earlier
        
        self.form.addRow(self.username_label, self.username_edit)
        self.form.addRow(self.password_label, self.password_edit)

        self.button_hbox = QHBoxLayout()

        # ... the widgets of the button hbox we defined earlier

        self.button_hbox.addItem(self.spacer_item)
        self.button_hbox.addWidget(self.login_button)

        self.main_vbox.addLayout(self.form)
        self.main_vbox.addLayout(self.button_hbox)

        self.central_widget.setLayout(self.main_vbox)
        self.setCentralWidget(self.central_widget)

We are done with our UI! To display it, we can add an if __name__ == "__main__" clause to the end of our code so that it creates a QApplication and shows our window only when the script is executed directly.

class MainWindow(QMainWindow):
    ... # the code we wrote earlier


if __name__ == "__main__":
    app = QApplication()

    window = MainWindow()
    window.show()

    raise SystemExit(app.exec())

window.show() is responsible for showing our main window and the app.exec() call at the end starts the Qt event loop so that our UI is displayed until the user dismisses it.

Notice how app.exec() is wrapped in a raise SystemExit(...) call. This is one of two ways (the other being sys.exit()) we can send the exit code that app.exec() returns so that it can be used by other applications calling our own to determine whether the app ran without errors.

Our final code should look like this.

from PySide6.QtWidgets import QApplication, QWidget, QHBoxLayout, QVBoxLayout, QFormLayout, QSpacerItem, QSizePolicy, QLabel, QLineEdit, QPushButton, QMainWindow

class MainWindow(QMainWindow):
    def __init__(self) -> None:
        super().__init__()

        self.central_widget = QWidget()

        self.main_vbox = QVBoxLayout()

        self.form = QFormLayout()

        self.username_label = QLabel("Username")
        self.username_edit = QLineEdit()

        self.password_label = QLabel("Password")
        self.password_edit = QLineEdit()
        
        self.form.addRow(self.username_label, self.username_edit)
        self.form.addRow(self.password_label, self.password_edit)

        self.button_hbox = QHBoxLayout()

        self.button_hbox.addItem(self.spacer_item)
        self.button_hbox.addWidget(self.login_button)

        self.button_hbox.addItem(self.spacer_item)
        self.button_hbox.addWidget(self.login_button)

        self.main_vbox.addLayout(self.form)
        self.main_vbox.addLayout(self.button_hbox)

        self.central_widget.setLayout(self.main_vbox)
        self.setCentralWidget(self.central_widget)


if __name__ == "__main__":
    app = QApplication()

    window = MainWindow()
    window.show()

    raise SystemExit(app.exec())

And our UI will look the same as with our Qt Designer example.

A few things you may have noticed

If you compare the generated code with our own, you will notice that ours includes less boilerplate. Writing the UI yourself provides a finer level of control and flexibility allowing you to design UIs quickly once you get into the rhythm of hand coding. However, it is crucial that you learn how to organize your UI so as to make it as separate from your application code as possible.

This example is simple by design so that you can quickly reproduce it on your end. However, you will likely want to split up the components either into methods within the main window or into separate widgets so that they’re more maintainable long term and also reusable in other places.

You may have also noticed that Qt uses a different naming convention than what we have used to define our variables. Qt uses the camelCase convention while we are using PEP 8’s snake_case convention. This is in line with the examples provided in the PySide documentation. However, you can choose the naming convention you’d like as long as you stay consistent, though a tendency towards Python’s conventions is appreciated.

Qt Designer vs Writing the UI Yourself

We have explored the two ways you can make your Qt user interface. You can use Qt Designer or you can write it yourself. This might leave you with a question: which method do I choose?

There’s a group of people that will tell you to not use Qt Designer for making UIs, especially when you’re a beginner. The common argument is that Qt Designer abstracts the process of creating the UI yourself: the process of defining widgets, creating layouts and windows, adding signals and slots, etc. Qt Widgets is a core part of the Qt ecosystem and by not writing the UI yourself you would be missing out on learning it.

While there is some truth to this sentiment, there are also many good things that come when using Qt Designer as a beginner:

1. Qt Designer is a quick and easy way of viewing and interacting with the set of Qt widgets available.
2. It is a simple way of prototyping your UI quickly increasing productivity.
3. Designer promotes separation of UI logic from application logic.

Those same advantages apply to anyone who works with Qt no matter their experience level. If you don’t want to spend time hand coding the GUI and all you want to focus on is your application logic, Qt Designer is definitely an appealing option. However, as we will see in the next section, there are many pitfalls you can end up in if you don’t use the Qt design tools properly.

Likewise, there are also many advantages when hand coding your UI, especially in places where Qt Designer simply cannot help you:

1. Once you get more experienced in Qt, your productivity when making UIs from scratch will likely be the same if not greater than when using Qt Designer.
2. Hand coding allows a finer level of control when creating UIs reducing boilerplate.
3. Hand coding will likely be the only option if you want to use custom widgets or if you want to dynamically update widgets and layouts.

However, in this environment, it also tends to become really easy to couple your UI logic with your application logic which, as you progress in making your UI, will be harder to decouple.

My recommendation, especially if you’re a beginner, is to test out each option: learn the basics of Qt Designer and learn the basics of Qt Widgets through hand coding. Pick the option that you feel most comfortable with and pick the best traits of both options. If you want to use Designer, do not modify the uic outputs. If you want to write the UI yourself, make sure to separate UI logic from application logic early on in your development process.

The Right (and Wrong) Way of Using UI Files

We have covered Qt Designer to a fair extent here. However, I also want to point out a common mistake that many beginners fall into when using Qt Designer, specifically when it comes to compiling your UI.

Let’s go back to the login form example we used earlier, which should look something like this:

Most tutorials about using Qt Designer in Python will at some point mention the Qt UI Compiler (also known as uic). This is a tool that will take your .ui file and convert it into Python code that can then be imported into your application.

You can use the Qt UI Compiler either from Qt Designer itself by going to Form > View Python Code or by using the uic command line tool. In PyQt, this tool will made available as called pyuic6. In PySide6, it will be called pyside6-uic. Both behave in practically the same way.

To convert your .ui file to a Python file, you can run the following:

pyside6-uic example.ui -o example.py

This will take your example.ui file and compile it into a file named example.py which will look something like this:

# -*- coding: utf-8 -*-

################################################################################
## Form generated from reading UI file 'example.ui'
##
## Created by: Qt User Interface Compiler version 6.9.0
##
## WARNING! All changes made in this file will be lost when recompiling UI file!
################################################################################

from PySide6.QtCore import (...)
from PySide6.QtGui import (...)
from PySide6.QtWidgets import (...)

class Ui_MainWindow(object):
    def setupUi(self, MainWindow):
        if not MainWindow.objectName():
            MainWindow.setObjectName(u"MainWindow")
        MainWindow.resize(297, 145)

        self.centralwidget = QWidget(MainWindow)
        # ... widget definitions would go here 

        MainWindow.setCentralWidget(self.centralwidget)
        
        # ... status bar and menu bar
        self.retranslateUi(MainWindow)

        QMetaObject.connectSlotsByName(MainWindow)
    # setupUi

    def retranslateUi(self, MainWindow):
        MainWindow.setWindowTitle(QCoreApplication.translate("MainWindow", u"MainWindow", None))
        # ... other translations
    # retranslateUi

Now, this is the point where we should be careful with what we do with this file. Unfortunately, most beginners (and some tutorials) go down the wrong route.

# -*- coding: utf-8 -*-

from PySide6.QtCore import (...)
from PySide6.QtGui import (...)
from PySide6.QtWidgets import (...)

class Ui_MainWindow(object):
    def setupUi(self, MainWindow):
        if not MainWindow.objectName():
            MainWindow.setObjectName(u"MainWindow")
        MainWindow.resize(297, 145)

        self.centralwidget = QWidget(MainWindow)

        self.pushButton = QPushButton(self.centralwidget)
        self.pushButton.setObjectName(u"pushButton")
        # ... more widget definitions would go here 

        MainWindow.setCentralWidget(self.centralwidget)
        
        # ... status bar and menu bar
        self.retranslateUi(MainWindow)

        QMetaObject.connectSlotsByName(MainWindow)
        
        # your new logic
        self.pushButton.clicked.connect(self.login)

    def retranslateUi(self, MainWindow):
        MainWindow.setWindowTitle(QCoreApplication.translate("MainWindow", u"MainWindow", None))
        # ... other translations

    def login(self):
        ... # do login work


if __name__ == "__main__":
    app = QApplication()

    ui = Ui_MainWindow()
    window = QMainWindow()
    
    ui.setupUi(window)
    window.show()

    raise SystemExit(app.exec())

## WARNING! All changes made in this file will be lost when recompiling UI file!

pyside6-uic example.ui -o example_ui.py

from PySide6.QtWidgets import QMainWindow, QApplication
from example_ui import Ui_MainWindow


class MainWindow(QMainWindow, Ui_MainWindow):
    def __init__(self) -> None:
        super().__init__()

        self.setupUi(self)


if __name__ == "__main__":
    app = QApplication()

    window = MainWindow()
    window.show()

    raise SystemExit(app.exec())

from PySide6.QtWidgets import QMainWindow, QApplication
from example_ui import Ui_MainWindow


class MainWindow(QMainWindow, Ui_MainWindow):
    def __init__(self) -> None:
        super().__init__()

        self.setupUi(self)

        # pushButton is the object name of our login button
        # you will probably want to rename it which you can do either
        # via the object inspector or via the properties panel in Designer.
        self.pushButton.clicked.connect(self.login)

    def login(self) -> None:
        ... # add your login functionality here


if __name__ == "__main__":
    app = QApplication()

    window = MainWindow()
    window.show()

    raise SystemExit(app.exec())

import sys
from PySide6.QtWidgets import QApplication
from PySide6.QtUiTools import QUiLoader

loader = QUiLoader()

app = QApplication()

window = loader.load("example.ui")
window.show()

raise SystemExit(app.exec())

from PyQt6.QtWidgets import QApplication
from PyQt6.uic import loadUi

app = QApplication()

window = loadUi("example.ui")
window.show()

raise SystemExit(app.exec())

pyside6-uic example.ui -o example_ui.py
python example.py

Conclusion

Hopefully, at this point, you should be able to decide for yourself whether Qt Designer is the right option for you. We have learned some of the basics of Qt Designer and how it compares to hand coding a UI.

We have also looked at the advantages and disadvantages of each approach plus common mistakes that you can make with each approach.

If you would like to learn more about Qt Designer, you can take a look at the Qt Widgets Designer manual in the Qt documentation.