Packaging with PyInstaller

37. Packaging with PyInstaller

PyInstaller is a cross-platform PyQt6 packaging system which supports building desktop applications for Windows, macOS and Linux. It automatically handles packaging of your Python applications, along with any associated libraries and data files, either into a standalone one-file executable or a distributable folder you can then use to create an installer.

In this chapter we’ll walk through the process using PyInstaller to package a PyQt6 application. The app we’ll be building is deliberately simple, including just a window and a few icons, but the same process can be used to build any of your own applications. We’ll cover customizing your application’s name, icons and bundling data files in a reproducible way. We’ll also cover some common issues which you may encounter when building your own apps.

Once we have built the application into a distributable executable, we’ll move onto creating Windows Installers, macOS Disk Images and Linux packages which you can share with other people.

ë

The source downloads for this book include complete build

examples for Windows, macOS and Ubuntu Linux.

j

You always need to compile your app on the target system. So, if

you want to build a Windows executable you’ll need to do this

on a Windows system.

Requirements

PyInstaller works out of the box with PyQt6 and as of writing, current versions of PyInstaller are compatible with Python 3.6+. Whatever project you’re working on, you should be able to package your apps. This tutorial assumes you have a working installation of Python with pip package management working.

You can install PyInstaller using pip.

pip3 install PyInstaller

If you experience problems packaging your apps, your first step should always be to update your PyInstaller and hooks packages to the latest versions using:

pip3 install --upgrade PyInstaller pyinstaller-hooks-contrib

The hooks module contains specific packaging instructions and workarounds for common Python packages and is updated more regularly than PyInstaller itself.

Getting Started

It’s a good idea to start packaging your application from the very beginning so you can confirm that packaging is still working as you develop it. This is particularly important if you add additional dependencies. If you only think about packaging at the end, it can be difficult to debug exactly where the problems are.

For this example we’re going to start with a simple skeleton app, which doesn’t do anything interesting. Once we’ve got the basic packaging process working, we’ll start extending things, confirming the build is still working at each step.

To start with, create a new folder for your application and then add the following app in a file named app.py.

Listing 247. packaging/basic/app.py

from PyQt6.QtWidgets import QMainWindow, QApplication, QPushButton

import sys

class MainWindow (QMainWindow):

def __init__ (self):

super().__init__()

self.setWindowTitle("Hello World")

button = QPushButton("My simple app.")

button.pressed.connect(self.close)

self.setCentralWidget(button)

self.show()

app = QApplication(sys.argv)

w = MainWindow()

app. exec ()

This is a basic bare-bones application which creates a custom QMainWindow and adds a simple QPushButton to it. Pressing the button will close the window. You can run this app as follows:

python app.py

This should produce the following window.

Figure 243. Simple app on Windows, macOS and Ubuntu Linux.

Building the basic app

Now that we have confirmed our simple application is working, we can create our first test build. Open your terminal (shell) and navigate to the folder containing your project. Run the following command to create a PyInstaller build.

pyinstaller --windowed app.py

ë

The --windowed command line option is required to build a .app

bundle on macOS and to hide the terminal output on Windows.

On Linux it has no effect.

You’ll see a number of messages output, giving debug information about what PyInstaller is doing. These are useful for debugging issues in your build, but can otherwise be ignored.

Listing 248. Output running pyinstaller on Windows

> pyinstaller app.py

388 INFO: PyInstaller: 4.7

388 INFO: Python: 3.7.6

389 INFO: Platform: Windows-10-10.0.22000-SP0

392 INFO: wrote app.spec

394 INFO: UPX is not available.

405 INFO: Extending PYTHONPATH with paths

....etc.

After the build is complete, look in your folder and you’ll notice you now have two new folders dist and build.

Figure 244. build & dist folders created by PyInstaller.

Below is a truncated listing of the folder structure showing the build and dist folders. The actual files will differ depending on which platform you’re building on, but the general structure is always the same.

.

├── app.py

├── app.spec

├── build

│ └── app

│ ├── localpycos

│ ├── Analysis-00.toc

│ ├── COLLECT-00.toc

│ ├── EXE-00.toc

│ ├── PKG-00.pkg

│ ├── PKG-00.toc

│ ├── PYZ-00.pyz

│ ├── PYZ-00.toc

│ ├── app

│ ├── app.pkg

│ ├── base_library.zip

│ ├── warn-app.txt

│ └── xref-app.html

└── dist

└── app

├── lib-dynload

...

The build folder is used by PyInstaller to collect and prepare the files for

bundling, it contains the results of analysis and some additional logs. For the most part, you can ignore the contents of this folder, unless you’re trying to debug issues.

The dist (for "distribution") folder contains the files to be distributed. This includes your application, bundled as an executable file, together with any associated libraries (for example PyQt6). Everything necessary to run your application will be in this folder, meaning you can take this folder and distribute it to someone else to run your app.

You can try running your built app yourself now, by running the executable file named app from the dist folder. After a short delay you’ll see the familiar window of your application pop up as shown below.

Figure 245. Simple app, running after being packaged.

In the same folder as your Python file, alongside the build and dist folders PyInstaller will have also created a .spec file.

The .spec file

The .spec file contains the build configuration and instructions that PyInstaller uses to package up your application. Every PyInstaller project has a .spec file, which is generated based on the command line options you pass when running pyinstaller.

When we ran pyinstaller with our script, we didn’t pass in anything other than the name of our Python application file. This means our spec file currently

contains only the default configuration. If you open it, you’ll see something similar to what we have below.

Listing 249. packaging/basic/app.spec

# -*- mode: python ; coding: utf-8 -*-

block_cipher = None

a = Analysis(['app.py'],

pathex=[],

binaries=[],

datas=[],

hiddenimports=[],

hookspath=[],

hooksconfig={},

runtime_hooks=[],

excludes=[],

win_no_prefer_redirects=False,

win_private_assemblies=False,

cipher=block_cipher,

noarchive=False)

pyz = PYZ(a.pure, a.zipped_data,

cipher=block_cipher)

exe = EXE(pyz,

a.scripts,

[],

exclude_binaries=True,

name='app',

debug=False,

bootloader_ignore_signals=False,

strip=False,

upx=True,

console=True,

disable_windowed_traceback=False,

target_arch=None,

codesign_identity=None,

entitlements_file=None )

coll = COLLECT(exe,

a.binaries,

a.zipfiles,

a.datas,

strip=False,

upx=True,

upx_exclude=[],

name='app')

The first thing to notice is that this is a Python file, meaning you can edit it and use Python code to calculate values for the settings. This is mostly useful for complex builds, for example when you are targeting different platforms and want to conditionally define additional libraries or dependencies to bundle.

If you’re building on macOS you’ll also have an additional BUNDLE block, which is used to build the .app bundle. That section will look something like this:

app = BUNDLE(coll,

name='app.app',

icon=None,

bundle_identifier=None)

If you’re starting your build on another platform, but want to target macOS later you can add this to the end of your .spec file manually.

Once a .spec file has been generated, you can pass this to pyinstaller instead of your script to repeat the previous build process. Run this now to rebuild your executable.

pyinstaller app.spec

The resulting build will be identical to the build used to generate the .spec file (assuming you have made no changes to your project). For many PyInstaller configuration changes you have the option of passing command-line arguments, or modifying your existing .spec file. Which you choose is up to you, although I would recommend editing the .spec file for more complex builds.

Tweaking the build

We’ve created a very simple application and build our first executable. Now we’ll look at a few things we can do to tweak the build.

Naming your app

One of the simplest changes you can make is to provide a proper "name" for your application. By default the app takes the name of your source file (minus the extension), for example main or app. This isn’t usually what you want to name the executable.

You can provide a nicer name for PyInstaller to use for your executable file (and dist folder) by editing the .spec file and changing the name= under the EXE and COLLECT blocks (and BUNDLE on macOS).

Listing 250. packaging/custom/hello-world.spec

exe = EXE(pyz,

a.scripts,

[],

exclude_binaries=True,

name='hello-world',

debug=False,

bootloader_ignore_signals=False,

strip=False,

upx=True,

console=True,

disable_windowed_traceback=False,

target_arch=None,

codesign_identity=None,

entitlements_file=None )

coll = COLLECT(exe,

a.binaries,

a.zipfiles,

a.datas,

strip=False,

upx=True,

upx_exclude=[],

name='hello-world')

The name under EXE is the name of the executable file while the name under COLLECT is the name of the output folder.

ë

I’d recommend you to use a name with no spaces for the

executable — use hyphens or CamelCase instead.

The name specified in the BUNDLE block is used for the macOS app bundle, which is the user-visible name of the application shown in Launchpad and on the dock. In our example we’ve called our application executable "hello-world", but for the .app bundle you can use the more friendly "Hello World.app".

Listing 251. packaging/custom/hello-world.spec

app = BUNDLE(coll,

name='Hello World.app',

icon=None,

bundle_identifier=None)

Alternatively, you can re-run the pyinstaller command and pass the -n or --name configuration flag along with your app.py script.

pyinstaller --windowed -n "hello-world" app.py

# or

pyinstaller --windowed --name "hello-world" app.py

The resulting executable file will be given the name hello-world and the unpacked build placed in the folder dist\hello-world. The name of the .spec file is taken from the name passed in on the command line, so this will also create a new spec file for you, called hello-world.spec in your root folder.

j

If you’ve created a new .spec delete the old one to avoid getting

confused!

Figure 246. Application with custom name "hello-world".

Application icon

Another simple improvement we can make is to change the application icon

which is shown while the application is running. We can set the icon for the application window/dock by calling .setWindowIcon() in the code.

Listing 252. packaging/custom/app.py

from PyQt6.QtWidgets import QMainWindow, QApplication, QPushButton

from PyQt6.QtGui import QIcon

import sys

class MainWindow (QMainWindow):

def __init__ (self):

super().__init__()

self.setWindowTitle("Hello World")

button = QPushButton("My simple app.")

button.pressed.connect(self.close)

self.setCentralWidget(button)

self.show()

app = QApplication(sys.argv)

app.setWindowIcon(QIcon("icon.svg"))

w = MainWindow()

app. exec ()

Here we’ve added the .setWindowIcon call to the app instance. This defines a default icon to be used for all windows of our application. You can override this on a per-window basis if you like, by calling .setWindowIcon on the window itself. Copy the icon into the same folder as your script.

If you run the above application you should now see the icon appears on the window on Windows and on the dock in macOS or Ubuntu Linux.

Figure 247. Windows showing the custom icon.

Z

A note about icons.

In this example we’re setting a single icon file, using a Scalable

Vector Graphics (SVG) file which will appear sharp at any size.

You can instead use bitmap images, in which case you will want

to provide multiple sizes to ensure the icon always appears

sharp. On Windows you can do this by building an ICO file,

which is a special file containing multiple icons. On Linux you

can provide multiple different PNG files during install (see the

Linux packaging section). On macOS the multiple icon sizes are

provided by an ICNS file included in the .app bundle.

Yes, this is confusing! But thankfully Qt supports the various

icon formats across all platforms.

j Even if you don’t see the icon, keep reading!

Dealing with relative paths

There is a gotcha here, which might not be immediately apparent. Open a shell and change to the folder where your script is saved. Run it as normal:

python3 app.py

If the icons are in the correct location, you should see them. Now change to the parent folder, and try and run your script again (change to the name of the folder your script is in).

cd ..

python3 /app.py

Figure 248. Window with icon missing.

The icons don’t appear. What’s happening?

We’re using relative paths to refer to our data files. These paths are relative to the current working directory — not the folder your script is in, but the folder you ran it from. If you run the script from elsewhere it won’t be able to find the files.

ë

One common reason for icons not showing up, is running

examples in an IDE which uses the project root as the current

working directory.

This is a minor issue before the app is packaged, but once it’s installed you don’t know what the current working directory will be when it is run — if it’s wrong your app won’t be able to find it’s data files. We need to fix this before we go any further, which we can do by making our paths relative to our application folder.

In the updated code below, we define a new variable basedir, using os.path.dirname to get the containing folder of file which holds the full path of the current Python file. We then use this to build the relative paths for data files using os.path.join().

ë

Take a look at Working with Relative Paths for more

information, and a more robust way of working with relative

paths in your apps.

Since our app.py file is in the root of our folder, all other paths are relative to that.

Listing 253. packaging/custom/app_relative_paths.py

import os

import sys

from PyQt6.QtGui import QIcon

from PyQt6.QtWidgets import QApplication, QMainWindow, QPushButton

basedir = os.path.dirname(__file__)

class MainWindow (QMainWindow):

def __init__ (self):

super().__init__()

self.setWindowTitle("Hello World")

button = QPushButton("My simple app.")

button.setIcon(QIcon(os.path.join(basedir, "icon.svg")))

button.pressed.connect(self.close)

self.setCentralWidget(button)

self.show()

app = QApplication(sys.argv)

app.setWindowIcon(QIcon(os.path.join(basedir, "icon.svg")))

w = MainWindow()

app. exec ()

Try and run your app again from the parent folder — you’ll find that the icon now appears as expected, no matter where you launch the app from.

Taskbar Icons (Windows Only)

On Windows .setWindowIcon() will correctly set the icon on your windows. However, due to how Windows keeps track of windows and groups them on the taskbar, sometimes the icon will not show up on the taskbar.

Z

If it does for you, great! But it may not work when you distribute

your application, so follow the next steps anyway!

When you run your application, Windows looks at the executable and tries to guess what "application group" it belongs to. By default, any Python scripts (which includes your application) are grouped under the same "Python" group, and so will show the Python icon. To stop this happening, we need to provide Windows with a different application identifier for our app.

The code below does this, by calling SetCurrentProcessExplicitAppUserModelID() with a custom application id.

Listing 254. packaging/custom/app_windows_taskbar.py

from PyQt6.QtWidgets import QMainWindow, QApplication, QPushButton

from PyQt6.QtGui import QIcon

import sys , os

basedir = os.path.dirname(__file__)

try : ①

from ctypes import windll # Only exists on Windows.

myappid = "mycompany.myproduct.subproduct.version" ②

windll.shell32.SetCurrentProcessExplicitAppUserModelID(myappid)

except ImportError:

pass

class MainWindow (QMainWindow):

def __init__ (self):

super().__init__()

self.setWindowTitle("Hello World")

button = QPushButton("My simple app.")

button.setIcon(QIcon(os.path.join(basedir, "icon.svg")))

button.pressed.connect(self.close)

self.setCentralWidget(button)

self.show()

app = QApplication(sys.argv)

app.setWindowIcon(QIcon(os.path.join(basedir, "icon.svg")))

w = MainWindow()

app. exec ()

①The code is wrapped in a try/except block since the windll module is not

available on non-Windows platforms. This allows your application to

continue working on macOS & Linux.

②Customize the app identifier string for your own applications.

The listing above shows a generic mycompany.myproduct.subproduct.version string, but you should change this to reflect your actual application. It doesn’t really matter what you put for this purpose, but the convention is to use reverse- domain notation, com.mycompany for the company identifier.

Add this to your script and your icon will definitely show on the taskbar.

Figure 249. Custom icon showing on the taskbar.

Executable icons (Windows only)

We now have the icon showing correctly while the application is running. But you may have noticed that your application executable still has a different icon. On Windows application executables can have icons embedded in them to make them more easily identifiable. The default icon is one provided by PyInstaller, but you can replace it with your own.

To add an icon to the Windows executable you need to provide an .ico format file to the EXE block.

Listing 255. packaging/custom/hello-world-icons.spec

exe = EXE(pyz,

a.scripts,

[],

exclude_binaries=True,

name='hello-world',

icon='icon.ico',

debug=False,

bootloader_ignore_signals=False,

strip=False,

upx=True,

console=True,

disable_windowed_traceback=False,

target_arch=None,

codesign_identity=None,

entitlements_file=None )

To create an .ico file, I recommend you use Greenfish Icon Editor Pro, a free and open-source tool which can also build icons for Windows. An example .ico file is included in the downloads with this book.

If you run the pyinstaller build with the modified .spec file, you’ll see the executable now has the custom icon.

Figure 250. Windows executable showing the default and custom icons.

ë

You can also provide the icon by passing --icon icon.ico to

pyinstaller on the initial build. You can provide multiple icons

this way to support macOS and Windows.

macOS .app bundle icon (macOS only)

On macOS applications are distributed in .app bundles, which can have their own icons. The bundle icon is used to identify the application in the Launchpad and on the dock when the application is launched. PyInstaller can take care of adding the icon to the app bundle for you, you just need to pass an ICNS format file to the BUNDLE block in the .spec file. This icon will then show up on the resulting bundle, and be shown when the app is started.

Listing 256. packaging/custom/hello-world-icons.spec

app = BUNDLE(coll,

name='Hello World.app',

icon='icon.icns',

bundle_identifier=None)

ICNS is the file format for icon files on macOS. You can create icon files on macOS using Icon Composer. You can also create macOS icons on Windows using Greenfish Icon Editor Pro.

Figure 251. macOS .app bundle showing the default and custom icons.

ë

You can also provide the icon by passing --icon icon.icns to

pyinstaller on the initial build. You can provide multiple icons

this way to support macOS and Windows.

In our example the icon set on the bundle will be replaced by the .setWindowIcon call when the application launches. However, on macOS you can skip the setWindowIcon() call entirely and just set the icon through the .app bundle if you

wish.

Data files and Resources

So we now have a application working, with a custom name, custom application icon and a couple of tweaks to ensure that the icon is displayed on all platforms and wherever the application is launched from. With this in place, the final step is to ensure that this icon is correctly packaged with your application and continues to be shown when run from the dist folder.

ë Try it, it wont.

The issue is that our application now has a dependency on a external data file (the icon file) that’s not part of our source. For our application to work, we now need to distribute this data file along with it. PyInstaller can do this for us, but we need to tell it what we want to include, and where to put it in the output.

In the next section we’ll look at the options available to you for managing data files associated with your app. This approach is not just for icon files, it can be used for any other data files, including Qt Designer .ui files, needed by your application.

Bundling data files with PyInstaller

Our application now has a dependency on a single icon file.

Listing 257. packaging/data-file/app.py

from PyQt6.QtWidgets import (

QMainWindow,

QApplication,

QPushButton,

QVBoxLayout,

QLabel,

QWidget,

)

from PyQt6.QtGui import QIcon

import sys , os

basedir = os.path.dirname(__file__)

try :

from ctypes import windll # Only exists on Windows.

myappid = "mycompany.myproduct.subproduct.version"

windll.shell32.SetCurrentProcessExplicitAppUserModelID(myappid)

except ImportError:

pass

class MainWindow (QMainWindow):

def __init__ (self):

super().__init__()

self.setWindowTitle("Hello World")

layout = QVBoxLayout()

label = QLabel("My simple app.")

label.setMargin( 10 )

layout.addWidget(label)

button = QPushButton("Push")

button.pressed.connect(self.close)

layout.addWidget(button)

container = QWidget()

container.setLayout(layout)

self.setCentralWidget(container)

self.show()

app = QApplication(sys.argv)

app.setWindowIcon(QIcon(os.path.join(basedir, "icon.svg")))

w = MainWindow()

app. exec ()

The simplest way to get this data file into the dist folder is to just tell PyInstaller to copy them over. PyInstaller accepts a list of individual file paths to copy over,

together with a folder path relative to the dist/ folder where it should to copy them to.

As with other options, this can be specified by command line arguments, --add -data which you can provide multiple times.

pyinstaller --add-data "icon.svg:." --name "hello-world" app.py

Z

The path separator is platform-specific, on Linux or Mac use :

while on Windows use ;

Or via the datas list in the Analysis section of the spec file, as a 2-tuple of source and destination locations.

a = Analysis(['app.py'],

pathex=[],

binaries=[],

datas=[('icon.svg', '.')],

hiddenimports=[],

hookspath=[],

runtime_hooks=[],

excludes=[],

win_no_prefer_redirects=False,

win_private_assemblies=False,

cipher=block_cipher,

noarchive=False)

And then execute the .spec file with:

pyinstaller hello-world.spec

In both cases we are telling PyInstaller to copy the specified file icon.svg to the location. which means the output folder dist. We could specify other locations here if we wanted. If you run the build, you should see your .svg file now in the output folder dist ready to be distributed with your application.

Figure 252. The icon file copied to the dist folder.

If you run your app from dist you should now see the icon as expected.

Figure 253. The icon showing on the window (Windows) and dock (macOS and Ubuntu)

ë

The file must be loaded in Qt using a relative path , and be in the

same relative location to the EXE as it was to the .py file for

this to work.

Z

If you start your build on a Windows machine, your .spec file

may end up containing paths using double back-slashes \\. This

will not work on other platforms, so you should replace these

with single forward-slashes /, which work on all platforms.

Bundling data folders

Usually you will have more than one data file you want to include with your packaged file. The latest PyInstaller versions let you bundle folders just like you would files, keeping the sub-folder structure. To demonstrate bundling folders of data files, lets add a few more buttons to our app and add icons to them. We can place these icons under a folder named icons.

Listing 258. packaging/data-folder/app.py

from PyQt6.QtWidgets import (

QMainWindow,

QApplication,

QLabel,

QVBoxLayout,

QPushButton,

QWidget,

)

from PyQt6.QtGui import QIcon

import sys , os

basedir = os.path.dirname(__file__)

try :

from ctypes import windll # Only exists on Windows.

myappid = "mycompany.myproduct.subproduct.version"

windll.shell32.SetCurrentProcessExplicitAppUserModelID(myappid)

except ImportError:

pass

class MainWindow (QMainWindow):

def __init__ (self):

super().__init__()

self.setWindowTitle("Hello World")

layout = QVBoxLayout()

label = QLabel("My simple app.")

label.setMargin( 10 )

layout.addWidget(label)

button_close = QPushButton("Close")

button_close.setIcon(

QIcon(os.path.join(basedir, "icons", "lightning.svg"))

)

button_close.pressed.connect(self.close)

layout.addWidget(button_close)

button_maximize = QPushButton("Maximize")

button_maximize.setIcon(

QIcon(os.path.join(basedir, "icons", "uparrow.svg"))

)

button_maximize.pressed.connect(self.showMaximized)

layout.addWidget(button_maximize)

container = QWidget()

container.setLayout(layout)

self.setCentralWidget(container)

self.show()

app = QApplication(sys.argv)

app.setWindowIcon(QIcon(os.path.join(basedir, "icons", "icon.svg")))

w = MainWindow()

app. exec ()

Z

The Windows taskbar icon fix is included in this code, you can

skip it if you are not building an application for Windows.

The icons (both SVG files) are stored under a subfolder named 'icons'.

.

├── app.py

└── icons

└── lightning.svg

└── uparrow.svg

└── icon.svg

If you run this you’ll see the following window, with icons on the buttons and an icon in the window or dock.

Figure 254. Window with multiple icons.

To copy the icons folder across to our build application, we just need to add the folder to our .spec file Analysis block. As for the single file, we add it as a tuple with the source path (from our project folder) and the destination folder under the resulting dist folder.

Listing 259. packaging/data-folder/hello-world.spec

# -*- mode: python ; coding: utf-8 -*-

block_cipher = None

a = Analysis(['app.py'],

pathex=[],

binaries=[],

datas=[('icons', 'icons')],

hiddenimports=[],

hookspath=[],

hooksconfig={},

runtime_hooks=[],

excludes=[],

win_no_prefer_redirects=False,

win_private_assemblies=False,

cipher=block_cipher,

noarchive=False)

pyz = PYZ(a.pure, a.zipped_data,

cipher=block_cipher)

exe = EXE(pyz,

a.scripts,

[],

exclude_binaries=True,

name='hello-world',

icon='icons/icon.ico',

debug=False,

bootloader_ignore_signals=False,

strip=False,

upx=True,

console=False,

disable_windowed_traceback=False,

target_arch=None,

codesign_identity=None,

entitlements_file=None )

coll = COLLECT(exe,

a.binaries,

a.zipfiles,

a.datas,

strip=False,

upx=True,

upx_exclude=[],

name='hello-world')

app = BUNDLE(coll,

name='Hello World.app',

icon='icons/icon.icns',

bundle_identifier=None)

If you run the build using this spec file you’ll now see the icons folder copied across to the dist folder. If you run the application from the folder — or anywhere else — the icons will display as expected, as the relative paths remain correct in the new location.

Wrapping up

With all these changes in place, you will now be able to reproducibly build your application on across all platforms. In the next chapters we’ll move onto taking our built executables and building them into working installers.

So far we’ve stepped through the process of building an application with PyInstaller on your own platform. Often you’ll want to build your app for all platforms.

As already mentioned, you can only build for a given platform on that platform — i.e. if you want to build a Windows executable, you’ll need to do it on Windows. However, ideally you want to be able to do this using the same .spec file, to simplify maintenance. If you want to target multiple platforms try your .spec file now on other systems to ensure the built is set up correctly. If something doesn’t work, check back at the platform-specific notes throughout this chapter.