This article is part of in the series
Last Updated: Wednesday 29th December 2021

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:

# setup.py
from distutils.core import setup
import py2exe

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:

cd dist

GUI Applications

Now it is time to create a GUI application. In this example we will be using Tkinter:
# tkexample.py
'''A very basic Tkinter example. '''
import Tkinter
from Tkinter import *
root = Tk()
root.title('A Tk Application')
Label(text='I am a label').pack(pady=15)

Then create setup.py, we can use the following code:
# setup.py
from distutils.core import setup
import py2exe


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:

# invoice.py
from reportlab.pdfgen import canvas
from reportlab.lib.pagesizes import letter
from reportlab.lib.units import mm

if __name__ == '__main__':
name = u'Mr. John Doe'
city = 'Pereira'
address = 'ELM Street'
phone = '555-7241'
c = canvas.Canvas(filename='invoice.pdf', pagesize= (letter[0], letter[1]/2))
c.setFont('Helvetica', 10)
# Print Customer Data
c.drawString(107*mm, 120*mm, name)
c.drawString(107*mm, 111*mm, city)
c.drawString(107*mm, 106*mm, address)
c.drawString(107*mm, 101*mm, phone)

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

# setup.py
from distutils.core import setup
import py2exe

options = {
'py2exe': {
'packages': ['reportlab']

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.

About The Author