PyQt Project Scaffold

Most of the time when you are setting up a a new PyQt5 project, you’re going to start from the same boilerplate so for the first article in this series, I’m going to show you the scaffold project I start with when I create new PyQt5 projects.

The file setup is very basic- there is an file, a file, a resources Python Package with a couple of files in it and a ui directory. is the main entry point for your PyQt5 project – there’s not a lot to it.  It tries to import resources (more on this further down) if you have setup any then it starts the Qt event loop.

import sys

from PyQt5.QtWidgets import QApplication

# try to import resources - this may throw an error as 
# the scaffold doesn't start with any resources
    from .resources import icons
except ImportError:

# create a qt application passing command line args
# docs -
app = QApplication(sys.argv)

# --- code to bootstrap project goes here

# start event loop
sys.exit(app.exec_()) is where all your global configuration goes so that it’s easily acccessible to the project.  The scaffold simply contains a couple of path settings, but I often put database and email server details in this file.

import sys
import os.path

BASE_PATH = os.path.realpath(sys.path[0])
UI_PATH = os.path.join(BASE_PATH, 'ui')

ui directory

The ui directory is not something we’ll be using immediately.  It’s intended purpose is to hold .ui files saved by Qt Designer – an excellent interface designer which sadly is no longer shipped with PyQt but can be installed with pip.

pip install pyqt5-tools

resources directory

The resources directory is for storing the assets used in the project.  Currently there is only an icons sub-directory, however there could be images, documents, etc. depending on the types of resources that the project requires.  The remainder of the files are the basic files needed to make use of Qt’s resource system.  The resource system allows you to compile all your assets into a python source file that you can import into your project so that you do not need to package and distribute your assets with you project.  make.bat is a simple batch file for Windows that runs the pyrcc5 resource compiler  and generates the Python module containing your assets.  In case you want to manually run the compiler or if you’re on a platform other that Windows, you can compile the .qrc file with the command pyrcc5 -o icons.qrc


icons.qrc is an XML file that tells the resource system which assets to compile.  I prefer to split out resource types into their own .qrc files for ease of management, but you could equally rename this file to resources.qrc if you are happy putting all assets in a single resource file.  Resources are added by inserting file tags like so <file alias='[[name]]'>[[path to file]]</file>


<RCC version="1.0">
    <qresource prefix='icons'>
        <!-- resources go here-->

Once you have compiled and imported the Python resource module, the resources setup in the .qrc file can be utilised where Qt expects a path by prepending it with a semicolon and and qresource prefix set in the .qrc file.  In the provided .qrc file this would look like :icons/[[name]]

The scaffolding setup can be cloned or downloaded from Github –

And that’s it!  In the next article we’re going to start looking at the basics of a Qt app, start playing with some widgets and look at how Qt manages windows.

Leave a Reply

Your email address will not be published. Required fields are marked *