PyInstaller Tutorial




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.


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

# Create only a single file (slower to run, easier to distribute)
pyinstaller -F

# Tell application not to launch console (e.g. PyQt5, GTK+, tkinter GUIs)
pyinstaller --noconsole

# Specify the icon file to use
pyinstaller --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

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
# Or, if you want the final distributable package to be a single file
pyi-makespec -F
# To set the icon
pyi-makespec --icon=icon.ico
# To disable console
pyi-makespec --noconsole
# Combined
pyi-makespec -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
    # ...
    # ...

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. 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
    # ...
    # ...

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.


After reading this tutorial, you should be able to create distributable Python applications using PyInstaller.