This is a guide on how to build a executable windows file from a Python script. It is especially focused on how to solve the problems that might occur while building a python QT application.

For me, it is important that I easily can distribute my applications and if you give someone who isn’t as geeky as yourself some Python script they most probably won’t know what to do with it. What we instead want to do is to create a executable file that can be run without having Python installed. This can be done with the help of py2exe.
A note for you cool Linux or Mac users out there: This guide only covers windows. Mac users can use py2app and follow guides on aralbalkan.com and tripmeter.in. You badass Linux users can find a guide at omgwtfgames.com. We at popdevelop might post a guide for you later on.
Lets start with the outline of what we need to do to build our executable:

  • Create a Python program
  • Download and install py2exe
  • Create a setup.py script
  • Run the setup.py script

Create a Python program

This shouldn’t be so hard, but since I’m a sucker for GUI applications I will give you two options here. Regardless of the option you choose in this example the scripts should be saved as “main.py”. The first option is to create a simple python script that prints “Hello Executable” in the console. This is done as shown below.

The second option is to use a QT GUI Python application. I wrote a guide here on popdevelop on how to do this last week so if you don’t know how to implement a GUI app using QT please follow the Setting up IDE and creating a cross platform QT Python GUI application guide. The code in script we used in that example is shown below and requires that you have installed PyQT.

Choose either of these options and continue to the next step.

Download and install py2exe

py2exe is an open source Python extension that allowes you to create executable Windows applications that can run without having Python installed on the computer. Installing py2exe in windows is as easy as installing anything else. Go to py2exe’s sourceforge page to download the installer. Use the one suitable for your Python version. In this guide we use Python 2.6 so we will download the one called “py2exe-0.6.9.win32-py2.6.exe”.
Execute the installation file. If you have installed Python the installation application should find your python installation and you should have something that looks like the figure below. Don’t you just love that blue color?!

The lovely py2exe installer

Step through the installation and py2exe should now be reachable from python. You can check this out by going to the python shell and importing py2exe. This is shown in the figure below.

Check that py2exe is installed

If this does not work you should troubleshoot the installation of Python or py2exe. Leave a comment on this post and I will try to help you out!

Create a setup.py script

To configure how you want the executable file to behave you will need to create a setup script. If modules are missing or if something goes wrong while creating your executable this is probably where you will fix it. For the first “Hello Executable” option used in this guide we won’t be needing anything fancy. The setup.py should contain the code shown below.

This will create a executable that has a console. To generate the executable go to the folder where your main.py and setup.py file is located and type: “python setup.py py2exe”. This will generate a “build” folder and a “distr” folder. In the distr folder you will find your .exe file.
If we used this setup.py script for our PyQT script we would get the error below:

Traceback (most recent call last):
File "main.py", line 1, in
File "PyQt4\QtCore.pyc", line 12, in
File "PyQt4\QtCore.pyc", line 10, in __load
ImportError: No module named sip

To fix this we will need to add a couple of things to the setup.py script. Below you see the script that solves the ImportError problems.

The first thing you might notice is that we changed “console” to “windows” in the setup call. What this does is that it runs a windows application with no console. Then the options parameter has been added making py2exe import Sip, which it complained about earlier and PyQt4.QtGui. The QtGui import is there because for some reason the application will not import PyQt4.QtCore from QtGui when py2exe has built it.


This guide shows you how to build an executable out of a python script. py2exe does this job well and after a couple of tweaks it will also build your PyQT application. If you have any problems while following this guide please leave a comment and I will try to fix it for you.

Further reading

Now that you’ve got your setup script and built your exe there might be some energy left in you so here’s a couple of sites that you might want to visit.

The peeps over at bytes.com has gotten their hands on some master setup.py file that should do everything for you. Read more…

eHow has a guide much like this one but a bit simpler. Read more…

Stackoverflow.com is an amazing site and there is of course a thread there where people are discussing alternatives to py2exe. Read more…

There is a thread over at devshed discussing py2exe. It’s dated but has lived from 2004 to 2009. Read more…

Update Jul 5, 2010

I found this guide at arstechnica.com named How-to: Deploying PyQt applications on Windows and Mac OS X. It also shows how to build a Mac version of your PyQt Python script.