PyInstaller Manual
Version: PyInstaller 2.1
Homepage: http://www.pyinstaller.org
Author: David Cortesi (based on structure by Giovanni Bajo & William Caban (based on
Gordon McMillan's manual))
Contact: rasky@develer.com
Revision: $Rev$
Source URL: $HeadURL$
Copyright: This document has been placed in the public domain.
PyInstaller Manual -
1
Contents
Requirements 4
License 5
How To Contribute 5
Installing PyInstaller 5
Installing Using pip 5
Installing in Windows 6
Installing from the archive 6
Verifying the installation 6
Installed commands 7
Overview: What PyInstaller Does and How It Does It 7
Analysis: Finding the Files Your Program Needs 7
Bundling to One Folder 8
Bundling to One File 8
How the One-Folder Program Works 8
How the One-File Program Works 9
Console or not? 9
Hiding the Source Code 9
Using PyInstaller 9
Options 10
General Options 10
Options for Finding Imported Modules and Libraries 11
Options for the Executable Output 11
Options for Windows apps 12
Options for Mac OS X apps 12
Building Mac OS X App Bundles 12
Setting a Custom Icon 13
Setting the Supported Document Types 13
Getting the Opened Document Names 13
Shortening the Command 13
Using UPX 14
Supporting Multiple Platforms 14
Supporting Multiple Python Environments 14
Supporting Multiple Operating Systems 15
Using Spec Files 15
Spec File Operation 16
PyInstaller Manual -
2
TOC Class (Table of Contents) 17
The Tree Class 17
Adding Files to the Bundle 18
Giving Run-time Python Options 19
When Things Go Wrong 19
Recipes and Examples for Specific Problems 19
Getting the Latest Version 19
Finding out What Went Wrong 20
Build-time Messages 20
Build-Time Python Errors 20
Getting Debug Messages 21
Getting Python's Verbose Imports 21
Helping PyInstaller Find Modules 21
Extending the Path 21
Listing Hidden Imports 21
Extending a Package's __path__ 22
Changing Runtime Behavior 22
Advanced Topics 23
The Bootstrap Process in Detail 23
Bootloader 23
Running Python code 23
Python imports in a frozen app 24
Adapting to being "frozen" 24
Accessing Data Files 25
Capturing Version Data 25
Inspecting Archives 26
ZlibArchive 26
CArchive 26
Using pyi-archive_viewer 27
Inspecting Executables 27
Multipackage Bundles 27
MERGE Function 28
Example MERGE spec file 28
Using Hook Files 29
Hooks in Detail 29
Building the Bootloader 31
PyInstaller Manual -
3
Development tools 31
Building 31
Linux Standard Base (LSB) binary 32
Modulefinder Replacement - ImportTracker 33
ImportTracker 33
analyze_one() 33
Module Classes 33
code scanning 33
Hooks 34
Warnings 34
Cross Reference 34
Outdated Features 34
Windows COM Server Support 34
Building Optimized 35
iu.py: An imputil Replacement 35
ImportManager 36
ImportDirector 36
PathImportDirector 36
Owner 36
Packages 36
Possibilities 37
Compatibility 37
Performance 37
Limitations 37
iu Usage 37
Requirements
Windows
• Windows XP or newer.
• PyWin32 Python extensions for Windows is needed for users of Python 2.6 and later.
Mac OS X
• Mac OS X 10.4 (Tiger) or newer (Leopard, Snow Leopard, Lion, Mountain Lion).
Linux
• ldd - Console application to print the shared libraries required by each program or shared library.
• objdump - Console application to display information from object files.
Solaris
PyInstaller Manual - Requirements
4
• ldd
• objdump
AIX
• AIX 6.1 or newer. Python executables created using PyInstaller on AIX 6.1 should work on AIX
5.2/5.3.
• ldd
• objdump
License
PyInstaller is distributed under the GPL License but it has an exception such that you can use it to compile
commercial products.
In a nutshell, the license is GPL for the source code with the exception that:
1. You may use PyInstaller to compile commercial applications out of your source code.
2. The resulting binaries generated by PyInstaller from your source code can be shipped with
whatever license you want.
3. You may modify PyInstaller for your own needs but changes to the PyInstaller source code fall
under the terms of the GPL license. That is, if you distribute your modifications you must
distribute them under GPL terms.
For updated information or clarification see our FAQ at the PyInstaller home page.
How To Contribute
PyInstaller is an open-source project that is created and maintained by volunteers. At Pyinstaller.org you
find links to the mailing list, IRC channel, and Git repository, and the important How to Contribute link.
Contributions to code and documentation are welcome, as well as tested hooks for installing other
packages.
Installing PyInstaller
Beginning with version 2.1 PyInstaller is a Python package and is installed like other Python packages.
Installing Using pip
The recommended method for Windows, Linux, or Mac OS is to use one of the standard package
installers such as pip (or the earlier easy_install). When you have installed one of these tools you can
download and install PyInstaller in one command, for example:
pip install pyinstaller
and upgrade to a newer version in one command:
pip install --upgrade pyinstaller
PyInstaller Manual - License
5