py2exe is a simple way to convert Python scripts into Windows .exe applications. It is an utility based in Distutils that allows you to run applications written in Python on a Windows 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. py2exe currently only works in Python 2.x.

First you need to download and install py2exe from the official sourceforge site

Now, in order to be able to create the executable we need to create a file called setup.py in the same folder where the script you want to be executable is located:

In the code above, we are going to create an executable for myscript.py. The setup function receives a parameter console=['myscript.py'] telling py2exe that we have a console application called myscript.py.

Then in order to create the executable just run python setup.py py2exe from the Windows command prompt (cmd). You will see a lot of output and then two folders will be created: dist and build. The build folder is used by py2exe 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. Note: Running python setup.py py2exe assumes that you have Python in your path environment variable. If that is not the case just use C:\Python27\python.exe setup.py py2exe.

Now test if your executable works:

GUI Applications

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

Then create setup.py, we can use the following code:

The setup function now is receiving a parameter windows=['tkexample.py'] telling py2exe that this is a GUI application. Again create the executable running python setup.py py2exe in the Windows command prompt. To run the application just navigate to the dist folder in the Windows Explorer and double-click tkexample.exe.

Using External Modules

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

In order to include the ReportLab module, we create a setup.py file, passing a options dictionary to the setup function:

The final step to be able to run the executable on other computers, is that the computer running the executable needs to have the Microsoft Visual C++ 2008 Redistributable package installed. A good guide explaining how to do this can be found here. Then just copy the dist folder to the other computer and execute the .exe file.

Finally please take into account the following recommendations:

  • The executable created most of the time is forward compatible: If you create the executable in Windows XP, it will run in Vista and 7. However it is not backwards-compatible: if you create the executable in Windows 7 it is not going to run on Windows XP.
  • If you have imported third party libraries, make sure to test all of the applications functionality before you ship the software, because sometimes the executable is created, but some libraries are missing. In that case you will get a runtime error when you try to access a functionality that uses the external library.
  • py2exe hasn't been updated since 2008, so it is not going to work with Python 3.

If you need more information about py2exe, visit the official site.

  • Absinthia Stacy

    does it work with python 3?

    • http://jacksonc.com Jackson Cooper

      Unfortunately not.

      I’d say your options are:

      1. cx_Freeze, which does support Python 3.x on any platform Python supports.
      2. Run your code through the 3to2 tool, which will convert the code to Python 2.x. Then you can use py2exe. However it’s not perfect, so YMMV.

      Good luck!

  • COBRACHOPPERGIRL

    Having to use a setup.py program is really gross and evil… if this were written properly, you should be able to compile your program.py directly, with py2exe program.py, which would produce program.exe. You pass the compiler your source file, and it produces a binary file. How can you screw that up?

    Well, the py2exe developer found a way to obfusicate things… unnecessarily. Any directives that are in setup.py should be able to be put in your source file header, and be done with.