Introduction
PyInstaller can be used to create .exe
files for Windows, .app files for Mac, and distributable packages for Linux.
Optionally, it can create a single file which is more convenient for
distributing, but takes slightly longer to start because it unzip itself.
This tutorial walks through the process of installing and using PyInstaller to create distributable packages.
Installation
To install PyInstaller, use pip and install the pyinstaller package.
pip install pyinstaller
Simple build
PyInstaller is not a cross-compiler, so it will only build a package for your current system. So, you must build Windows from Windows, Mac from Mac, and Linux from Linux.
# Build the .exe, .app, or linux executable distribution
pyinstaller hello.py
# Create only a single file (slower to run, easier to distribute)
pyinstaller hello.py -F
# Tell application not to launch console (e.g. PyQt5, GTK+, tkinter GUIs)
pyinstaller hello.py --noconsole
# Specify the icon file to use
pyinstaller hello.py --icon=path/to/icon.ico
The output will be in a folder named dist/.
Build with .spec file
For more complex builds, it can help to first create a .spec file which
defines all the files that should be included and any other settings.
You can read more about spec files at https://pythonhosted.org/PyInstaller/spec-files.html.
Generate the .spec file
To generate a .spec file, use pyi-makespec which comes with the pyinstaller
package. Provide pyi-makespec the Python file/application you want to
package and it will generate the spec file.
Note that you can pass all the regular command-line flags that you would
pass to pyinstaller to pyi-makespec and it will include those options
in the spec file.
# Create a spec file with all defaults
pyi-makespec myapp.py
# Or, if you want the final distributable package to be a single file
pyi-makespec myapp.py -F
# To set the icon
pyi-makespec myapp.py --icon=icon.ico
# To disable console
pyi-makespec myapp.py --noconsole
# Combined
pyi-makespec myapp.py -F --icon=icon.ico --noconsole
Tweak the .spec file
Modify the .spec file to meet your needs.
This may include adding resource files like images, icons, configuration
files, or the Designer .ui templates. Additionally, you might want
to disable the console if it is a GUI application.
Include files
To add arbitrary files, modify the line in the .spec file that
contains datas=[]. It should contain a list of tuples.
Each tuple should contain two values, the file(s) to include,
and the target directory. For example, to include all .ui files
in your templates/ directory in to a templates/ directory of your
final distributable package, modify the spec file like this:
# Change `datas=[]` to this:
# ...
datas=[('templates/*.ui', 'templates')],
# ...
Disable console
If you have a GUI application, such as a PyQt5, Tkinter, PyGame,
or GTK+ application, you might want to disable the console so a window
with the command prompt does not show up in addition to the regular
desired GUI window. You can disable the console by changing Console=True
in the .spec file to Console=False like this:
# Change `console=True` to False in the `exe` object
# ...
console=False
# ...
Change the file icon
If you need to create a .ico icon file, you could use one of the following:
Inedo's Icon Maker can be downloaded from the GitHub releases as a .zip file.
Unzip the file to get IconMaker.exe. Run it, and drag your image file in to
the window. It accepts up to 256x256 pixel images.
Icoconvert.com allows you to upload an image and get a .ico file back.
To change the icon that the .exe has, you can pass the --icon=icon.ico
to the pyi-makespec command or modify the .spec file yourself by altering
the exe object to add the argument icon='icon.ico'.
# Change or add `icon='icon.ico'` to `exe` object
# ...
icon='path/to/icon.ico'
# ...
Build the package
Once the .spec file is up to your standards, use pyinstaller and pass
it the .spec file as the first argument. It will use the information
specified in the file to create the final distributable package.
pyinstaller myapp.spec
The output will be in the dist/ folder the same as building without
the .spec file.
Conclusion
After reading this tutorial, you should be able to create distributable Python applications using PyInstaller.