py2exe is an open-source tool that converts Python scripts into standalone, runnable Windows executable (*.exe) programs, allowing execution on Windows systems that do not have Python installed. It is compatible with a wide range of Python frameworks including wxPython, Tkinter, Pmw, PyGTK, pygame, win32com client and server applications, and many others.

Installing py2exe

You can install py2exe directly from the command line with:

easy_install py2exe

After installation, verify the installation with this test in the Python shell:

C:\>python
Python 2.7.6 (default, Nov 10 2013, 19:24:18) [MSC v.1500 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import py2exe
>>>

If no errors are thrown, the installation is complete and working.

Common Installation Issues

Error: no module named machinery

This error indicates an incompatible version mismatch. py2exe version 0.9 and above only supports Python 3.x. To use py2exe with Python 2.7, you must install the 0.6.x release, which you can download here: http://sourceforge.net/projects/py2exe/files/py2exe/0.6.9/

You can also install the specific version directly via easy_install:

easy_install py2exe-0.6.9.win32-py2.7.exe

easy_install often fails to resolve compatible versions, so manual download is generally more reliable. When downloading manually, select the package matching your system architecture:

• 32-bit Python 2.7: py2exe-0.6.9.win32-py2.7.exe
• 64-bit Python 2.7: py2exe-0.6.9.win64-py2.7.amd64.exe

Error: Python version 2.7 required, which was not found in the registry

There are several common solutions for this error:

1. For 32-bit systems: The simplest fix is to uninstall any existing 64-bit Python installation and reinstall 32-bit Python 2.7.
2. For 64-bit systems keeping 64-bit Python: You can get pre-built compatible py2exe binaries from the unofficial community repository of Windows Python extension packages.
3. Recommended fix: After downloading the correct py2exe installer, create a script named register_python.py with the following content, then run the script to fix the registry entry:

import sys
from _winreg import *

target_version = sys.version[:3]
install_location = sys.prefix

registry_path = "SOFTWARE\\Python\\Pythoncore\\%s\\" % target_version
install_entry = "InstallPath"
python_path_entry = "PythonPath"
full_python_path = "%s;%s\\Lib\\;%s\\DLLs\\" % (
    install_location, install_location, install_location
)

def register_python():
    try:
        reg_handle = OpenKey(HKEY_CURRENT_USER, registry_path)
    except EnvironmentError as e:
        try:
            reg_handle = CreateKey(HKEY_CURRENT_USER, registry_path)
            SetValue(reg_handle, install_entry, REG_SZ, install_location)
            SetValue(reg_handle, python_path_entry, REG_SZ, full_python_path)
            CloseKey(reg_handle)
        except:
            print "*** Unable to register Python installation!"
            return
        print "--- Python %s registered successfully!" % target_version
        return
    existing_install = QueryValue(reg_handle, install_entry)
    existing_path = QueryValue(reg_handle, python_path_entry)
    if existing_install == install_location and existing_path == full_python_path:
        CloseKey(reg_handle)
        print "=== Python %s is already registered correctly!" % target_version
        return
    CloseKey(reg_handle)
    print "*** Unable to complete registration!"
    print "*** You likely have another Python installation registered in the registry!"

if __name__ == "__main__":
    register_python()

After running this script, you can run the py2exe installer normally, and the error will be resolved.

Usage

To build a EXE from your Python script, first create you're main application script, for example hello.py. Next, create a build setup script (usually named setup.py), making sure to import py2exe before calling the setup function. A sample setup script for a console application looks like this:

from distutils.core import setup
import py2exe

setup(console=["hello.py"])

Run the build with the following command:

python setup.py py2exe

Once the build completes, a new dist subdirectory will be created, containing your hello.exe, the matching Python core DLL, library.zip, and all required dependencies. Any C extension modules used by your application will be copied into this directory automatically, along with any non-system DLLs they require. All files in the dist directory are required to run your application, so distribute the entire contents of this folder to end users.

By default, py2exe creates the following required files in the dist directory:

1. One or more output executable files
2. The Python core DLL matching your Python version
3. Compiled extension modules (.pyd) and all non-system DLLs required by these extensions
4. A library.zip file that stores compiled pure Python modules (.pyc/.pyo)

The example above builds a console-based application. To build a GUI application that does not launch a console window at runtime, replace the console paramter with windows like this:

setup(windows=["hello.py"])

py2exe can build multiple executable files in a single run. Just pass the full list of your scripts to the console or windows keyword argument, which is useful for distributing a set of related applications.

To view all available command line options for py2exe, run:

python setup.py py2exe --help