Create Python GUI Apps on Raspberry Pi With PyQt

I use Python for many Raspberry Pi projects, especially when working with GPIO pins or automating simple tasks. But running a script in the terminal is one thing; giving it a clean, user-friendly interface is another. PyQt is one of the easiest ways to build this.

PyQt is a library that can be used to create GUI applications with Python. On Raspberry Pi OS, it’s available in the default repository and can be installed via the package manager (APT).

I’ll briefly explain how PyQt works, then walk you through the installation and help you build your first GUI application on Raspberry Pi.

If you’re like me and sometimes mix up syntax between programming languages, I’ve got just the thing for you. I’ve put together a Python cheat sheet with all the essential syntax in one place, so you can keep it handy and avoid any confusion. Download it here for free!

What is PyQt?

As the name suggests, PyQt is a mix between Python and Qt.

Python is the default programming language used on Raspberry Pi. It’s preinstalled on Raspberry Pi OS, with many additional libraries already available for you. I have many articles about Python and the Raspberry Pi on this website, so I recommend checking these if you are new to this:

• Why Is Python Used On Raspberry Pi? (3 huge reasons)
• Should You Learn Linux or Python first?
• How to Learn to Program in Python with a Raspberry Pi?

Qt is basically the main application framework used to create applications with a graphic user interface (GUI). It’s written in C++ and works on all platforms (Windows, Linux, macOS and even smartphone systems).

So, PyQt is the toolkit you need to access this framework in Python. The goal is to create graphic applications within your Python code. For example, create a window with buttons that will do specific actions instead of doing everything from a terminal.

Let’s learn how to set up your Raspberry Pi to use it, and I’ll show you a few examples – everything will be clearer after that.

How to Install PyQt on Raspberry Pi

There are two ways to get PyQt on Raspberry Pi: you can either use APT to get the stable version from the default repository or use PIP to install the latest version available.

Method 1: Install PyQt with APT

Using the package manager (APT) is the most natural way to get PyQt installed on your Raspberry Pi. I tested it on Raspberry Pi OS, but it should work the same on all Debian-based distributions.

Open a terminal and type this command to install PyQt on your system:
sudo apt install python3-pyqt6

APT will install it in a few seconds, taking care of the required dependencies if needed.

Note: I noticed that the older release, PyQt5, was already installed on my Raspberry Pi. So maybe it’s already installed on the full version of Raspberry Pi OS.

Tip: Command lines can be a pain to memorize. I put the essential Linux commands on a printable cheat sheet so you don't have to keep googling them. You can grab the PDF here if you want to save some time.

Method 2: Install PyQt with PIP

The official repository is generally a few versions behind, so if you want the latest version, you’ll have to use a different installation method.

For personal projects, I would recommend the APT method above, as it’s easier and will stay up-to-date automatically with your system updates. However, if you need a specific version, using PIP is a good alternative.

If you’ve never used PIP before, let’s install the prerequisites to use it:
sudo apt install python3-pip python3-venv
To avoid the “externally-managed-environment” error, create a Python virtual environment:
python -m venv myproject
source myproject/bin/activate

Update the pip packages available:
pip install --upgrade pip

You can then install the latest version of PyQt:
pip install pyqt6

Note: If you still need the older PyQt5, it’s also available via PIP:
pip install PyQt5

Since you’ll be building applications, you’ll probably also want the Qt development headers:
sudo apt install qt6-base-dev


If you are new to this, I would recommend reading this article for more details about Python libraries: How to Install and Use Python Packages on Raspberry Pi?

Getting Started with PyQt on Raspberry Pi

Now that PyQt6 is installed on your Raspberry Pi, let’s try to use it.
The syntax is not as straightforward as with other libraries, so I’ll try to deconstruct it for you, starting with something really basic and building up from there.

First Script

A minimalist script you can create to generate your first window looks like this:

from PyQt6.QtWidgets import QApplication, QMainWindow
import sys

app = QApplication([])
win = QMainWindow()

win.show()

sys.exit(app.exec())

• PyQt6 is a gigantic library, so it’s good practice to only import the class you need (QApplication and QMainWindow for this example).
• Then we create an application and a window, with the default options (no parameters).
• Finally, we call win.show() to display the window we just created.
• sys.exit() is used to make sure the program is stopped when we close the app.

You can copy this code into your favorite editor. I recommend using Thonny for these first tests.
When you click Run, you should get a blank application window appear, like this:

As I mentioned, it’s really the minimum we can do without adding more complicated functions.
It’s just showing an empty window on your screen.

Note: If you want to see these steps in action, I have a video series on Python just for community members. Join here to watch, and get access to 30+ other lessons for Raspberry Pi along with many other benefits!

Let’s see how to add some basic elements to it and configure it a bit more.

Basic Elements

From there, you can improve your script a little to:

• Adjust the window size and position on your screen.
• Add text in the window (so you can use this for error messages for example).
• Add a button to start a specific action for your project.

Window Size and Position

The QMainWindow class comes with a few functions you can use to set the window title and size:

• setWindowTitle(<title>): will set the window title to whatever you want.
• resize(<width>,<height>): set the default size for the new window.

You can call these functions from the “win” object we created in the first script, so it will look like:

win = QMainWindow()
win.setWindowTitle("Your Title")
win.resize(500,200)

I will give you a full example at the end of this article. Let me introduce a few other things first.

Add Text in Your Window

To display text in your new window, you need to create a new object: a label.
It’s like a text area in PowerPoint.
You define it, type the text, resize the box, and choose the position.

The code to do this looks like that:

label = QLabel("This is my dumb text", win)
label.adjustSize()
label.move(20, 0)

You need to import QLabel on the first line of your script or it won’t work (check the first line in the full script below).

We use the constructor to define the initial text and which window it’s attached to. Next, we tell the label to resize itself to fit the text. Finally, the move function places the text in a specific location.

Create a Button

Buttons are probably the thing you’ll use the most, as using this library just to display text is a bit too complicated for the result. Anyway, adding a button in your window is a lot like adding text.

The only difference is that we need to link the click-on-the-button link to a specific action.

Here is the sample of my code where I create the button:

button = QPushButton("Click here", win)
button.move(20,40)
button.clicked.connect(clickMethod)

Don’t forget to import QPushButton at the top.

It’s the same idea as before , we use QPushButton to define it and set the text on it.
Then the move function places the button wherever you want.

The last line tells what the button should do.
In this example, I call the “clickMethod” function when the button is clicked.

Here is my full script with all these elements:

from PyQt6.QtWidgets import QApplication, QMainWindow, QLabel, QPushButton
import sys

def clickMethod():
    print("Button clicked!")
    
app = QApplication([])
win = QMainWindow()
win.setWindowTitle("Your Title")
win.resize(500,200)

label = QLabel("This is my text", win)
label.adjustSize()
label.move(100, 0)

button = QPushButton("Click here", win)
button.move(100,40)
button.clicked.connect(clickMethod)

win.show()

sys.exit(app.exec())

When you run the script, the window now looks like this:

So, on the window, you have a different title, a text and then a button.
If you click on the button, it executes the clickMethod() function, and shows “Button clicked” in the console.

Obviously, you’ll edit the function, so it does whatever you need for your specific project. But you get the idea.

Going Further with PyQt

I hope this introduction tutorial gave you a basic understanding of how to use PyQt on your Raspberry Pi. Try to play a bit more with these elements, change the values in my script, and add other text labels and buttons with different actions to make sure everything is clear.

Once done, you can check the official documentation to learn about the other classes, functions and parameters you can use:

• Official doc: https://doc.qt.io/qtforpython/
• Python doc: https://wiki.python.org/moin/PyQt/Tutorials

This documentation is useful to get an idea of all the possibilities of this library, but I find that even basic examples are pretty complicated for beginners. That’s why I recommend starting from my example and adding new features from there.

And remember that if you are new to Python, it’s probably not the first tutorial you should try. Start with something easier and get back to this later. Here are a few suggestions:

• 15 Fun Raspberry Pi Projects to Experiment with Python
• How To Use The Raspberry Pi Camera With Python
• How to program Minecraft with Python on a Raspberry Pi?

Not getting the same result?

Even when you follow every step, small differences in OS version, hardware or config can change the outcome. Instead of wasting time guessing, get help from people who have already fixed the same kind of issue.

Ask your question now →

🔒 No risk. Cancel anytime.

• Get help on your exact issue
• Access step-by-step videos for tricky setups
• Browse the website without ads