The first step in creating desktop applications with Pyqt is getting a window to show up on your desktop. Thankfully, with PyQt that is pretty simple.

Below are a few short examples to creating PyQt apps and getting a window on the screen. If this works you know you have Qt set up correctly & you can start creating your applications! The following examples are written for Python 3 with PyQt5, but can be easily adapted for other versions.

PyQt5 is not officially supported on Python 2.7, and trying to use it just makes things more difficult. If you *can * use Python 3 you should.

Creating an application

Below is a bare-minimum PyQt application, which actually doesn't even include a window. If you run it "nothing" will happen, but it should work.

import sys
from PyQt5.QtWidgets import QApplication

# You need one (and only one) QApplication instance per application.
# Pass in sys.argv to allow command line arguments for your app.
# If you know you won't use command line arguments QApplication([]) is fine.
app = QApplication(sys.argv)

# Start the event loop.
app.exec_()

# Your application won't reach here until you exit and the event
# loop has stopped.

Stepping through the code line-by-line, we start by importing the PyQt5 classes that we need for the application, from the QtWidgets submodule.

Next we create an instance of QApplication, passing in sys.arg (which contains command line arguments). This allows us to pass command line arguments to our application. If you know you won't be accepting command line arguments you can pass in an empty list instead, e.g.

app = QApplication([])

Finally, we call app.exec_() to start up the event loop. If you watch the console while your application is running you'll notice it does not reach the print("Finished") until you exit the app. This is because Qt sits in the app.exec_() event loop until the application is quit.

If you need anything to happen during start-up it should be before this line. Usually a simple solution is to handle setup during the __init__ for your main window object.

Creating a window

The last example was pretty boring, because there was nothing to see. Let's add a window to our desktop application so we have something to look at. The code below is a bare-minimum single-window application in PyQt.

import sys
from PyQt5.QtWidgets import QApplication, QWidget

app = QApplication(sys.argv)

window = QWidget()
window.show() # IMPORTANT!!!!! Windows are hidden by default.

# Start the event loop.
app.exec_()

Any QWidget without a parent (containing widget) is it's own window. This is a fine way to create windows, however there is also a specific QMainWindow class. This has a few advantages for use as a main window in an application including support for toolbars, status bars and dockable widgets. To use QMainWindow just swap it out in the code:

import sys
from PyQt5.QtWidgets import QApplication, QMainWindow

app = QApplication(sys.argv)

window = QMainWindow()
window.show() # IMPORTANT!!!!! Windows are hidden by default.

# Start the event loop.
app.exec_()

Running the above you should see an empty window on your desktop, the below is the appearance on Mac OS. Exciting isn't it?

My first widget

So that was still pretty dull, just opening up an empty window on your desktop. Let's make it a little bit more interesting by adding a basic text QLabel widget. A QMainWindow can only hold a single widget, which you set via .setCentralWidget().

If you want to add more widgets and arrange them, you need to use Qt layouts.

import sys
from PyQt5.QtWidgets import QApplication, QLabel, QMainWindow
from PyQt5.QtCore import Qt

# Subclass QMainWindow to customise your application's main window
class MainWindow(QMainWindow):

    def __init__(self, *args, **kwargs):
        super(MainWindow, self).__init__(*args, **kwargs)

        self.setWindowTitle("My Awesome App")

        label = QLabel("This is a PyQt5 window!")

        # The `Qt` namespace has a lot of attributes to customise
        # widgets. See: http://doc.qt.io/qt-5/qt.html
        label.setAlignment(Qt.AlignCenter)

        # Set the central widget of the Window. Widget will expand
        # to take up all the space in the window by default.
        self.setCentralWidget(label)


app = QApplication(sys.argv)

window = MainWindow()
window.show()

app.exec_()

When you run this you should see the window on your desktop as before, but this time also with the label from the QLabel visible in the middle. The window is resizeable by dragging the edges, and the alignment setting should keep the text centered in the window.