Freezing with PyInstaller & Nuitka

Pygame GUI has some support for turning your application into an executable using either PyInstaller or Nuitka. Be aware however that these utilities working successfully is also dependent on the version of python you are using, support in any other libraries you are using (including pygame CE) and your own handling of data files.

As a general principle it is better to be slightly back from the bleeding edge of Python progress if you want to successfully freeze your python scripts into an exe. Both nuitka and PyInstaller are community projects and as such are dependent on the python community to keep pace with core python development. There is usually some amount of lag.

That out of the way, lets look at each of them more closely.


First things first you will need to have the PyInstaller package from PyPI:

pip install pyinstaller

Once that is installed you need to create a .spec file for your project that will handle gathering up all the data files you are using and any other options you might wish to use. There are a lot of options for spec files and you can read more about them in the pyinstaller documentation.

Here is one I cooked up for the pyinstaller_example script in the pygame_gui_examples repository:

 1# -*- mode: python -*-
 3block_cipher = None
 6a = Analysis(['../'],
 7             pathex=[],
 8             binaries=[],
 9             datas=[],
10             hiddenimports=[],
11             hookspath=[],
12             runtime_hooks=[],
13             excludes=[],
14             win_no_prefer_redirects=False,
15             win_private_assemblies=False,
16             cipher=block_cipher)
18a.datas += Tree('data', prefix='data')
20pyz = PYZ(a.pure, a.zipped_data,
21          cipher=block_cipher)
23# enable this to see verbose output
24# options = [ ('v', None, 'OPTION')]
25exe = EXE(pyz,
26          a.scripts,
27          # options,
28          exclude_binaries=True,
29          name='pyinstaller_test_release',
30          debug=False, # set this to True for debug output
31          strip=False,
32          upx=True,
33          console=True ) # set this to False this to remove the console
34coll = COLLECT(exe,
35               a.binaries,
36               a.zipfiles,
37               a.datas,
38               strip=False,
39               upx=True,
40               name='pyinstaller_test_release')

Once you have your spec file, and made sure it includes any custom data you are using in your script (fonts, images, sounds, theme files etc) you are ready to try and compile the executable.

pyinstaller path_to_your_spec_file.spec

Pygame GUI now includes a Pyinstaller 'hook' file which should bring in all the data files used by Pygame GUI itself, however if you are using other packages that have their own data files you may have to manage this process yourself.

Good luck, and make yourself known on the GitHub issues page if you have any problems.


As with PyInstaller, when using Nuitka the first step is to download it:

pip install nuitka

Once you've done that you need to carefully specify the Nuitka command line to include all the data directories for pygame_gui (along with any data directories for any other libraries you are using).

The crucial line is:


Here is an example command line:

nuitka --onefile --plugin-enable=numpy --plugin-enable=pylint-warnings --include-plugin-directory=pygame_gui/data -o package/YourExeName.exe --output-dir=package

There haven't been as many users of the Pygame GUI asking about Nuitka yet, so I am not as familiar with any other issues that may arise. Please check out the official documentation for more information on Nuitka.

As always let us know any issues you have on the GitHub issues page.