Links

If you find any error or any stupid inconsistency in this small manual about compiler switches, please let me know. A patch would be extremely welcome, but in any case contact me at:
andrea.gavana@gmail.com
gavana@kpo.kz

Enjoy GUI2Exe, wxPython rules :-D

py2exe

Last updated: 01 April 2007

This section provides information about the compiler switches (aka options) available when compiling a Python script using py2exe. Most of the options available with py2exe have been implemented in GUI2Exe, and the exceptions are clearly marked in this file.

Exe Kind

This variable can assume two values (at the moment). It can be either "windows" or "console", depending on the kind of executable you wish to build:

  • windows: builds an executable for a GUI-based application;
  • console: creates an executable for a console program (i.e., no graphical interface stuff involved).

The other options currently available in py2exe, namely service, com_server and ctypes_com_server are currently not implemented in GUI2Exe .

If you're interested in one of the missing options, please let me know (I have never used them).

Python Main Script

You should assign to this variable the name of your main Python script for which you want to build the executable. For example, if we want to build an executable for the wxPython demo, the Python Main Script is:

%YourPath%/wxPython2.X Docs and Demos/demo/Main.py

Optimize

This switch represents the optimization level for the compiled bytecode. This variable can assume 3 values:

  • 0 (Python): No optimization on the compiled bytecode (default);
  • 1 (Python -O): Optimize the generated bytecode;
  • 2 (Python -OO): remove doc-strings in addition to the -O optimizations.

I usually stick with the value of 2, unless some package (i.e., matplotlib in the past), complains about the missing __doc__.

Compressed

This option, if activated, creates a compressed zip archive (zipfile). It can be either 0 or a positive number, the meaning of activating/deactivating the compression is as follows:

  • No Compression: the zipfile will be created using the zipfile.ZIP_STORED Python option;
  • With Compression: the zipfile will be created using the zipfile.ZIP_DEFLATED Python option.

If you specify the Skip Archive option, compression can not be activated (no zipfile to compress).

Compression activated will obviously create a smaller zipfile.

Bundle Files

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

  • One (or more) exe files;
  • The python#.#.dll;
  • A couple of .pyd files which are the compiled extensions that the exe files need, plus any other .dll files that the extensions need;
  • 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 appended to the .exe files and not present in the dist directory).

This 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. 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.

The Bundle Files option is currently not available on 64 bit machines (py2exe 0.6.6).

Zipfile

By activating this option in GUI2Exe, you can specify a name for the compressed zip file where py2exe will put all the bytecode-compiled Python modules. If you don't activate this option, or the zipfile name is empty, the default in GUI2Exe is to use zipfile=None. This means the compiled bytecode will be attached to the executable itself and no zip file will be created in your dist directory.

If you specify the Skip Archive option, zipfile can not be None.

Dist Directory

If you activate this switch, you will be able to specify the name of the directory to put final built distributions in (the default is "dist").

Includes And Friends

This section deals with the options py2exe offers to forcibly include (or exclude, or ignore) Python modules, packages and Windows dlls. Py2exe accepts this options as comma-separated lists of strings, and in particular the options are:

  • Excludes: comma-separated list of Python modules to exclude;
  • Dll-Excludes: comma-separated list of DLLs to exclude;
  • Ignores: comma-separated list of Python modules to ignore if they are not found;
  • Includes: comma-separated list of Python modules to include;
  • Packages: comma-separated list of Python packages to include.

You can easily add this items in GUI2Exe by simply clicking on the list control you wish to edit and hitting Ctrl+A to add items. To remove them, you can select the items and either hit Del on the keyboard or right-click and choose "Delete selected".

The Includes option is stronger than the Excludes one. So, if a module is present in both Includes and Excludes, it will be included in your final distribution.

Data Files

Py2exe allows you to include one (or more) series of files that you are going to need to run your executable. For example, to run my GUIs as executable, I ask py2exe to create a folder called "images" where I put all my icons and another one called "matplotlibdata" to include the matplotlib data files.
In GUI2Exe, you can just repeat the procedure described in section Includes And Friends, select all the files you need in one shot and specify the name of the folder where py2exe will put the data files.

Resources

This section deals with the possible resources you can include in your executable file. For example, speaking about GUIs, if you want to assign an icon to your application, you need to specify the "icon_resources" to py2exe. Moreover, when distributing your application on other PCs, it is good practice to include also the "manifest file", a file that instructs Windows on how to correctly render the widgets in you user interface. This file lives under "other_resources" in py2exe.
In GUI2Exe , you just need to click on XP Manifest File check box and it will be automagically inserted in the appropriate list control (and obviously in the final Setup.py file). The GUI2Exe list controls for icon_resources, bitmap_resources and other_resources work exactly as described in section Includes And Friends.

Cross Reference

This command line switch instructs py2exe to create a Python module cross reference and display it in the webbrowser. This allows to answer question why a certain module has been included, or if you can exlude a certain module and its dependencies. Also, the html page includes links which will even allow to view the source code of a module in the browser, for easy inspection.

Ascii

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 switching on this option in its associated check box in GUI2Exe .

Skip Archive

By choosing this option, py2exe will copy the Python bytecode files directly into the dist directory and subdirectories (or in the excutable itself). No zipfile archive is used.

Custom Boot Script

By selecting a file for this option, your custom Python file can do things like installing a customized stdout blackhole. The custom boot script is executed during startup of the executable immediately after boot_common.py is executed.