26.2 The py2exe Tool

The distutils help you package up your Python extensions and applications. However, an end user can install the resulting packaged form only after installing Python. This is particularly a problem on Windows, where end users want to run a single installer to get an application working on their machine. Installing Python first and then running your application's installer may prove too much of a hassle for such end users.

Thomas Heller has developed a simple solution, a distutils add-on named py2exe, freely available for download from http://starship.python.net/crew/theller/py2exe/. This URL also contains detailed documentation of py2exe, and I recommend that you study that documentation if you intend to use py2exe in advanced ways. However, the simplest kinds of use, which I cover in the rest of this section, cover most practical needs.

After downloading and installing py2exe (on a Windows machine where Microsoft Visual C++ 6 is also installed), you just need to add the line:

import py2exe

at the start of your otherwise normal distutils script setup.py. Now, in addition to other distutils commands, you have one more option. Running:

python setup.py py2exe

builds and collects in a subdirectory of your distribution root directory an .exe file and one or more .dll files. If your distribution's name metadata is, for example, myapp, then the directory into which the .exe and .dll files are collected is named dist\myapp\. Any files specified by option data_files in your setup.py script are placed in subdirectories of dist\myapp\. The .exe file corresponds to your application's first or single entry in the scripts keyword argument value, and also contains the bytecode-compiled form of all Python modules and packages that your setup.py specifies or implies. Among the .dll files is, at minimum, the Python dynamic load library, for example python22.dll if you use Python 2.2, plus any other .pyd or .dll files that your application needs, excluding .dll files that py2exe knows are system files (i.e., guaranteed to be available on any Windows installation).

py2exe provides no direct means to collect the contents of the dist\myapp\ directory for easy distribution and installation. You have several options, ranging from a .zip file (which may be given an .exe extension and made self-extracting, in ways that vary depending on the .zip file handling tools you choose), all the way to a professional Windows installer construction system, such as those sold by companies such as Wise and InstallShield. One option that is particularly worth considering is Inno Setup, a free, professional-quality installer construction system (see http://www.jrsoftware.org/isinfo.php). Since the files to be packaged up for end user installation are an .exe file, one or more .dll files, and perhaps some data files in subdirectories, the issue becomes totally independent from Python. You may package up and redistribute such files just as if they had originally been built from sources written in any other programming language.