py2exe.jpg

py2exe - convert python scripts into standalone windows programs

Copyright (c) 2001-2008 Thomas Heller, Mark Hammond, Joachim Bauch, Jimmy Retzlaff, and contributors.

Abstract

py2exe is a Python distutils extension which converts python scripts into executable windows programs, able to run without requiring a python installation.

It has been used to create wxPython, Tkinter, Pmw, PyGTK, pygame, win32com client and server modules and other standalone programs.

py2exe is distributed under an open-source license. It contains code originally written by Joachim Bauch, released under the Mozilla Public License Version 1.1

News

py2exe 0.6.9 released (2008/11/15)

Binaries for Python 2.6 and Python 2.7.

Fixed a modulefinder crash on certain relative imports.

Changed the py2exesamplessinglefileguitest_wx.py sample to use the wx package instead of the old wxPython package.

Copy the manifest, if any, from the 'template' into the targets to ensure embedded assembly references, as required for python 2.6 based apps, are copied.

Allow each target to specify Vista User Access Control flags. For example, specifying 'uac_execution_info="requireAdministrator"' would force elevation for the final executable.

py2exe 0.6.8 released (2008/06/15)

Support for relative imports.

Fix MemoryLoadLibrary to handle loading function addresses by ordinal numbers. Patch and test by Matthias Miller.

Using the options compressed=1, bundle_files=3, and zipfile=None at the same time now works; patch from Alexey Borzenkov.

Allow renaming of single-executable files; patch from Alexey Borzenkov.

Embedding icon resources into the image now works correctly even for ico files containing multiple images.

pyd files from different packages with the same filename no longer conflict. Patch from Grant Edwards.

There are new samples for the 'typelibs' support, including the new option of pre-generating a typelib and specifying the file as an input to py2exe.

The test suite is now included in the source distribution.

py2exe 0.6.6 released (2006/12/30)

Better support for Python 2.5.

Experimental support for 64-bit builds of Python on win64.

Better ISAPI support.

New samples for ISAPI and COM servers.

Support for new "command-line styles" when building Windows services.

py2exe 0.6.5 released (2006/03/20)

Fixed modulefinder / mf related bugs introduced in 0.6.4. This will be most evident when working with things like win32com.shell and xml.xpath.

Files no longer keep read-only attributes when they are copied as this was causing problems with the copying of some MS DLLs.

py2exe 0.6.4 released (2006/02/13)

New skip-archive option which copies the Python bytecode files directly into the dist directory and subdirectories - no archive is used.

An experimental new custom-boot-script option which allows a boot script to be specified (e.g., --custom-boot-script=cbs.py) which can do things like installing a customized stdout blackhole. See py2exe's boot_common.py for examples of what can be done. The custom boot script is executed during startup of the executable immediately after boot_common.py is executed.

Thomas Heller's performance improvements for finding needed modules.

Mark Hammond's fix for thread-state errors when a py2exe created executable tries to use a py2exe created COM DLL.

py2exe 0.6.3 released (2005/10/06)

dll-excludes is now available on the command line and can be used to exclude msvcr71.dll and w9xpopen.exe.

A bug that caused py2exe to crash when copying extension modules in packages was fixed.

py2exe 0.6.2 released (2005/09/07)

Several important bugfixes.

For Python 2.4, MSVCR71.dll is now copied into the dist directory. This dll cannot be bundled into the executable, sorry.

py2exe 0.6.1 released (2005/09/05)

Can now create single file executables.

Documentation

You are reading it ;-). A lot of other, user supplied documentation is in the WIKI.

Please don't mail me directly about py2exe, please use the py2exe mailing list, which is also available on gmane, via http and nntp.

What's new in py2exe 0.6

  • The new --bundle <level> or -b <level> command line switch instructs py2exe to bundle needed dlls and pyds into the library file or the executable itself, instead of simply collecting them in the dist directory. Not only does this create less files you have to distribute, it also allows Python inprocess COM servers to run completely isolated from other Python interpreters in the same process. See below for more details.
  • To prevent unicode encoding error, py2exe now by default includes the codecs module and the encodings package. If you are sure your program never implicitely or explicitely has to convert between unicode and ascii strings this can be prevented by the --ascii or -a command line switch.
  • It is no longer required to clean the build directory from time to time to prevent some strange errors.
  • Several patches have been integrated (if you miss a patch you sent me, please send it again. It can be that I missed some mails).

The announcement, and the ChangeLog.

Some comments about py2exe 0.5, still valid for 0.6

The documentation is still to be written, but there is quite some info available in the included samples, and in the WIKI pages. Thanks to everyone who contributed.

Python 2.3 or 2.4 is required, because the new zipimport feature is used. The zipimport mechanism is able to handle the early imports of the warnings and also the encodings module which is done by Python.

Using py2exe

Assuming you have written a python script myscript.py which you want to convert into an executable windows program, able to run on systems without a python installation. If you don't already have written a distutils setup-script, write one, and insert the statement import py2exe before the call to the setup function:

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

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

Running

python setup.py py2exe --help

will display all available command-line flags to the py2exe command.

Now you can call the setup script like in this way:

python setup.py py2exe

and a subdirectory dist will be created, containing the files myscript.exe, python23.dll, and library.zip. If your script uses compiled C extension modules, they will be copied here as well, also all dlls needed at runtime (except the system dlls).

These files include everything that is needed for your program, and you should distribute the whole directory contents.

The above setup script creates a console program, if you want a GUI program without the console window, simply replace console=["myscript.py"] with windows=["myscript.py"].

py2exe can create more than one exe file in one run, this is useful if you have a couple of related scripts. Pass a list of all scripts in the console and/or windows keyword argument.

Specifying additional files

Some applications need additional files at runtime, like configuration files, fonts, or bitmaps.

py2exe can copy these files into subdirectories of dist if they are specified in the setup script with the data_files option. data_files should contain a sequence of (target-dir, files) tuples, where files is a sequence of files to be copied.

Here's an example:

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

setup(console=["myscript.py"],
      data_files=[("bitmaps",
                   ["bm/large.gif", "bm/small.gif"]),
                  ("fonts",
                   glob.glob("fonts\\*.fnt"))],
)

This would create a subdirectory dist\bitmaps, containing the two .gif files, and a subdirectory dist\fonts, containing all the .fnt files.

Windows NT services

You can build Windows NT services by passing a service keyword argument to the setup function, the value must be a list of Python module names containing a service class (identified by the _svc_name_ attribute):

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

setup(service=["MyService"])

Optionally, you can specify a 'cmdline-style' attribute to py2exe, with valid values being 'py2exe' (the default), 'pywin32' or 'custom'. 'py2exe' specifies the traditional command-line always supported by py2exe. 'pywin32' supports the exact same command-line arguments as pywin32 supports (ie, the same arguments supported when running the service from the .py file.) 'custom' means that your module is expected to provide a 'HandleCommandLine' function which is responsible for all command-line handling.

The built service executables are able to install and remove themselves by calling them with certain command line flags, run the exe with the -help argument to find out more.

COM servers

COM servers are built by passing a com_server keyword argument to the setup function, again the value must be a list of Python module names containing one or more COM server classes (identified by their _reg_progid_ attribute):

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

setup(com_server=["win32com.server.interp"])

By default both DLL and EXE servers are built, you should simply delete those you don't need.

The bundle option

By default py2exe creates these files in the dist directory which you must deploy:

  1. One (or more) .exe files
  2. The python##.dll
  3. A couple of .pyd files which are the compiled extensions that the exe files need, plus any other .dll files that the extensions need.
  4. A library.zip file which contains the compiled pure python modules as .pyc or .pyo files (if you have specified 'zipfile=None' in the setup script this file is append to the .exe files and not present in the dist-directory).

The --bundle <level> or -b <level> command line switch will create less files because binary extensions, runtime dlls, and even the Python-dll itself is bundled into the executable itself, or inside the library-archive if you prefer that.

The bundled pyds and dlls are never unpacked to the file system, instead they are transparently loaded at runtime from the bundle. The resulting executable appears to be statically linked.

Specifying a level of 2 includes the .pyd and .dll files into the zip-archive or the executable. Thus, the dist directory will contain your exe file(s), the library.zip file (if you haven't specified 'zipfile=None'), and the python dll. The advantage of this scheme is that the application can still load extension modules from the file system if you extend sys.path at runtime.

Using a level of 1 includes the .pyd and .dll files into the zip-archive or the executable itself, and does the same for pythonXY.dll. The advantage is that you only need to distribute one file per exe, which will however be quite large. Another advantage is that inproc COM servers will run completely isolated from other Python interpreters in the same exe. The disadvantage of this scheme is that it is impossible to load other extensions from the file system, the application will crash with a fatal Python error if you try this. I have still to find a way to prevent this and raise an ImportError instead - any suggestions how this can be implemented would be very welcome.

The bundle-option has been tested with some popular extensions, but of course there's no guarantee that any extension will work in bundled form - be sure to test the executable (which you should do anyway).

The bundle option achieves its magic by code which emulates the Windows LoadLibrary api, it is compiled into the exe-stubs that py2exe uses. For experimentation, it is also installed as a normal Python extension _memimporter.pyd in the lib\site-packages directory. The Python module zipextimported.py in the same directory demonstrates how it can be used to load binary extensions from zip-files.

Samples

The py2exe-installer installs some examples into the lib\site-packages\py2exe\samples directory, demonstrating several simple and advances features.

The singlefile subdirectory contains two samples which are built as single-file executables: a trivial wxPython gui program, and a pywin32 dll COM server module.

How does it work?

py2exe uses python's modulefinder to examine your script and find all python and extension modules needed to run it. Pure python modules are compiled into .pyc or .pyo files in a temporary directory. Compiled extension modules (.pyd) are also found and parsed for binary dependencies.

A zip-compatible archive is built, containing all python files from this directory. Your main script is inserted as a resource into a custom embedded python interpreter supplied with py2exe, and the zip-archive is installed as the only item on sys.path.

In simple cases, only pythonxx.dll is needed in addition to myscript.exe. If, however, your script needs extension modules, unfortunately those cannot be included or imported from the zip-archive, so they are needed as separate files (and are copied into the dist directory).

Attention: py2exe tries to track down all binary dependencies for all pyds and dlls copied to the dist directory recursively, and copies all these dependend files into the dist directory. py2exe has a builtin list of some system dlls which are not copied, but this list can never be complete.

Installing py2exe

Download and run the installer py2exe-0.6.9.win32-py2.3.exe (for Python 2.3), py2exe-0.6.9.win32-py2.4.exe (for Python 2.4), py2exe-0.6.9.win32-py2.5.exe (for Python 2.5), py2exe-0.6.9.win64-py2.5.amd64.msi (for 64-bit Python 2.5), py2exe-0.6.9.win32-py2.6.exe (for Python 2.6), py2exe-0.6.9.win64-py2.6.amd64.exe (for 64-bit Python 2.6), py2exe-0.6.9.win32-py2.7.exe (for Python 2.7), or py2exe-0.6.9.win64-py2.7.amd64.exe (for 64-bit Python 2.7).

This installs py2exe together with some samples, the samples are in the lib\site-packages\py2exe\samples subdirectory.

For Windows 95/98/Me, you need the Microsoft Layer for Unicode on Windows 95/98/ME Systems (MSLU) dll from here (Internet Explorer is required to download it: Scroll down to the Win95/98/Me section).

Download and run the self-extracting unicows.exe file, and copy the unpacked unicows.dll file in the directory which contains your python.exe. Note that this is only needed on the machine where you want to build executables with py2exe, it is not required on the machine where you want to run the created programs.

If you use py2exe to build COM clients or servers, win32all build 163 (or later) is strongly recommened - it contains much better support for frozen executables.

Project information

The project is hosted at SourceForge Logo.