Last Updated: Wednesday 14th August 2013

PyInstaller is a program used to convert Python scripts into standalone applications. PyInstaller allows you to run applications written in Python on a computer without requiring the user to install Python. It is an excellent option when you need to distribute a program to the end user as a standalone application. PyInstaller currently only works with Python 2.3 up to 2.7.

PyInstaller claims to be compatible with a lot of third party libraries or packages out of the box. PyQt, Django and matplotlib are fully supported.

To start, download and extract PyInstaller from the official site.

PyInstaller is an application, not a package. So there is no need to install it in your computer. To get started, open a Command Prompt (Windows) or a Terminal (Mac and Linux) and go to the PyInstaller Folder.

Now suppose you want to package, I saved it into the pyinstaller folder:

Then, in order to create the executable just run python and you will see a lot of output and a folder called myscript will be created, with two folders and a file inside. The build folder is used by PyInstaller as a temporary folder to create the files needed for the executable. The dist folder stores the executable and all of the files needed in order to run that executable. It is safe to delete the build folder. The file called myscript.spec is useful to customize the way PyInstaller packs your application.

Now test if your executable works:

You should see now a "Hello World!" printed on the screen.

Remember that running python assumes that you have Python in your path environment variable. If that is not the case, just use C:\Python27\python.exe in Windows. Most of the time on Linux and Mac OS X, Python will be in your path environment variable.

GUI Applications

Now it is time to create a GUI application. In this example we will be using Tkinter:

To pack it, it is mandatory to use the --windowed flag, otherwise the application will not start:

In this moment you can navigate to the dist folder and run the application by double clicking it.

Note for Mac OS X users: the above example using Tkinter works fine if you use the pre-installed Python version, if you installed or updated Python by yourself, you can find some problems running the packaged application.

Using External Modules

The previous examples were importing modules from the Python Standard Library. PyInstaller includes the Standard Library Modules by default. However if we installed a third party library, PyInstaller is likely not to include it. In most of the cases we need to create "hooks" to tell PyInstaller to include these modules. An example of this is an application using the ReportLab library to make PDF files:

A "hook" module is a Python file with a special name, used to tell PyInstaller to include a specific module. Doing a Google search i found the needed hooks to pack a ReportLab application here and placed them in a folder named "hooks":

+- hooks/
|- and are empty files, contains:

Now in order to pack the executable, we have to run python --additional-hooks-dir=hooks/ The additional-hooks-dir flag tells PyInstaller to search for hooks in the specified directory.


Pyinstaller works great if your script only imports modules from The Python Standard Library, or a module included in the official Supported Packages list. Using these supported packages make packaging applications pretty straightforward, but when wee need to use a third-party not supported module, it can be tricky to make it work.