What's New This Release

Release 3.0 is a major rewrite that adds Python 3 support, better code quality through use of automated testing, and resolutions for many old issues.

Functional changes include removal of support for Python prior to 2.7, an easier way to include data files in the bundle (Adding Files to the Bundle), and changes to the "hook" API (Understanding PyInstaller Hooks).

Windows

PyInstaller runs in Windows XP or newer. It can create graphical windowed apps (apps that do not need a command window).

It requires the PyWin32 or pypiwin32 Python extension for Windows. The latter is installed automatically if you install PyInstaller using pip. The pip-Win package is recommended, but not required.

Mac OS X

PyInstaller runs in Mac OS X 10.6 (Snow Leopard) or newer. It builds 64-bit executables by default, but can create 32-bit executables. It can build graphical windowed apps (apps that do not use a terminal window).

Linux

PyInstaller requires the ldd terminal application to discover the shared libraries required by each program or shared library. It is typically found in the distribution-package glibc or libc-bin.

It also requires the objdump terminal application to extract information from object files. This is typically found in the distribution-package binutils.

AIX, Solaris, and FreeBSD

Users have reported success running PyInstaller on these platforms, but it is not tested on them. The ldd and objdump commands are needed.

Before using PyInstaller in these systems you must compile a bootloader; see Building the Bootloader.

Installing in Windows

For Windows, PyWin32 or the more recent pypiwin32, is a prerequisite. The latter is installed automatically when you install PyInstaller using pip or easy_install. If necessary, follow the pypiwin32 link to install it manually.

It is particularly easy to use pip-Win to install PyInstaller along with the correct version of PyWin32. pip-Win also provides virtualenv, which makes it simple to maintain multiple different Python interpreters and install packages such as PyInstaller in each of them. (For more on the uses of virtualenv, see Supporting Multiple Platforms below.)

When pip-Win is working, enter this command in its Command field and click Run:

venv -c -i  pyi-env-name

This creates a new virtual environment rooted at C:\Python\pyi-env-name and makes it the current environment. A new command shell window opens in which you can run commands within this environment. Enter the command

pip install PyInstaller

Once it is installed, to use PyInstaller,

• Start pip-Win
• In the Command field enter venv pyi-env-name
• Click Run

Then you have a command shell window in which commands such as pyinstaller execute in that Python environment.

Installing in Mac OS X

PyInstaller works with the default Python 2.7 provided with current Mac OS X installations. However, if you plan to use a later version of Python, or if you use any of the major packages such as PyQt, Numpy, Matplotlib, Scipy, and the like, we strongly recommend that you install these using either MacPorts or Homebrew.

PyInstaller users report fewer problems when they use a package manager than when they attempt to install major packages individually.

Installing from the archive

If pip is not available, download the compressed archive from PyPI. If you are asked to test a problem using the latest development code, download the compressed archive from the develop branch of PyInstaller at GitHub.

Expand the archive. Inside is a script named setup.py. Execute python setup.py install with administrator privilege to install or upgrade PyInstaller.

For platforms other than Windows, Linux and Mac OS, you must first build a bootloader program for your platform: see Building the Bootloader. After the bootloader has been created, use python setup.py install with administrator privileges to complete the installation.

Verifying the installation

On all platforms, the command pyinstaller should now exist on the execution path. To verify this, enter the command

pyinstaller --version

The result should resemble 3.n for a released version, and 3.ndev-xxxxxx for a development branch.

If the command is not found, make sure the execution path includes the proper directory:

• Windows: C:\PythonXY\Scripts where XY stands for the major and minor Python verysion number, for example C:\Python34\Scripts for Python 3.4)
• Linux: /usr/bin/
• OS X (using the default Apple-supplied Python) /usr/local/bin
• OS X (using Python installed by macports) /opt/local/bin

To display the current path in Windows the command is echo %path% and in other systems, echo $PATH.

Installed commands

The complete installation places these commands on the execution path:

• pyinstaller is the main command to build a bundled application. See Using PyInstaller.
• pyi-makespec is used to create a spec file. See Using Spec Files.
• pyi-archive_viewer is used to inspect a bundled application. See Inspecting Archives.
• pyi-bindepend is used to display dependencies of an executable. See Inspecting Executables.
• pyi-grab_version is used to extract a version resource from a Windows executable. See Capturing Windows Version Data.

If you do not perform a complete installation (installing via pip or executing setup.py), these commands will not be installed as commands. However, you can still execute all the functions documented below by running Python scripts found in the distribution folder. The equivalent of the pyinstaller command is pyinstaller-folder/pyinstaller.py. The other commands are found in pyinstaller-folder /cliutils/ with meaningful names (makespec.py, etc.)

Analysis: Finding the Files Your Program Needs

What other modules and libraries does your script need in order to run? (These are sometimes called its "dependencies".)

To find out, PyInstaller finds all the import statements in your script. It finds the imported modules and looks in them for import statements, and so on recursively, until it has a complete list of modules your script may use.

PyInstaller understands the "egg" distribution format often used for Python packages. If your script imports a module from an "egg", PyInstaller adds the egg and its dependencies to the set of needed files.

PyInstaller also knows about many major Python packages, including the GUI packages Qt (imported via PyQt or PySide), WxPython, TkInter, Django, and other major packages. (For a complete list of supported packages see LINK HERE)

Some Python scripts import modules in ways that PyInstaller cannot detect: for example, by using the __import__() function with variable data, or manipulating the sys.path value at run time. If your script requires files that PyInstaller does not know about, you must help it:

• You can give additional files on the pyinstaller command line.
• You can give additional import paths on the command line.
• You can edit the myscript.spec file that PyInstaller writes the first time you run it for your script. In the spec file you can tell PyInstaller about code modules that are unique to your script.
• You can write "hook" files that inform PyInstaller of hidden imports. If you create a "hook" for a package that other users might also use, you can contribute your hook file to PyInstaller.

If your program depends on access to certain data files, you can tell PyInstaller to include them in the bundle as well. You do this by modifying the spec file, an advanced topic that is covered under Using Spec Files. (LINK TARGET TO CHANGE).

In order to locate included files at run time, your program needs to be able to learn its path at run time in a way that works regardless of whether or not it is running from a bundle. This is covered under Run-time Operation.

PyInstaller does not include libraries that should exist in any installation of this OS. For example in Linux, it does not bundle any file from /lib or /usr/lib, assuming these will be found in every system.

Bundling to One Folder

When you apply PyInstaller to myscript.py the default result is a single folder named myscript. This folder contains all your script's dependencies, and an executable file also named myscript (myscript.exe in Windows).

You compress the folder to myscript.zip and transmit it to your users. They install the program simply by unzipping it. A user runs your app by opening the folder and launching the myscript executable inside it.

It is easy to debug problems that occur when building the app when you use one-folder mode. You can see exactly what files PyInstaller collected into the folder.

Another advantage of a one-folder bundle is that when you change your code, as long as it imports exactly the same set of dependencies, you could send out only the updated myscript executable. That is typically much smaller than the entire folder. (If you change the script so that it imports more or different dependencies, or if the dependencies are upgraded, you must redistribute the whole bundle.)

A small disadvantage of the one-folder format is that the one folder contains a large number of files. Your user must find the myscript executable in a long list of names or among a big array of icons. Also your user can create a problem by accidentally dragging files out of the folder.

How the One-Folder Program Works

A bundled program always starts execution in the PyInstaller bootloader. This is the heart of the myscript executable in the folder.

The PyInstaller bootloader is a binary executable program for the active platform (Windows, Linux, Mac OS X, etc.). When the user launches your program, it is the bootloader that runs. The bootloader creates a temporary Python environment such that the Python interpreter will find all imported modules and libraries in the myscript folder.

The bootloader starts a copy of the Python interpreter to execute your script. Everything follows normally from there, provided that all the necessary support files were included.

(This is an overview. For more detail, see The Bootstrap Process in Detail below.)

Bundling to One File

PyInstaller can bundle your script and all its dependencies into a single executable named myscript (myscript.exe in Windows).

The advantage is that your users get something they understand, a single executable to launch. A disadvantage is that any related files such as a README must be distributed separately. Also, the single executable is a little slower to start up than the one-folder bundle.

Before you attempt to bundle to one file, make sure your app works correctly when bundled to one folder. It is is much easier to diagnose problems in one-folder mode.

How the One-File Program Works

The bootloader is the heart of the one-file bundle also. When started it creates a temporary folder in the appropriate temp-folder location for this OS. The folder is named _MEIxxxxxx, where xxxxxx is a random number.

The one executable file contains an embedded archive of all the Python modules used by your script, as well as compressed copies of any non-Python support files (e.g. .so files). The bootloader uncompresses the support files and writes copies into the the temporary folder. This can take a little time. That is why a one-file app is a little slower to start than a one-folder app.

After creating the temporary folder, the bootloader proceeds exactly as for the one-folder bundle, in the context of the temporary folder. When the bundled code terminates, the bootloader deletes the temporary folder.

(In Linux and related systems, it is possible to mount the /tmp folder with a "no-execution" option. That option is not compatible with a PyInstaller one-file bundle. It needs to execute code out of /tmp.)

Because the program makes a temporary folder with a unique name, you can run multiple copies of the app; they won't interfere with each other. However, running multiple copies is expensive in disk space because nothing is shared.

The _MEIxxxxxx folder is not removed if the program crashes or is killed (kill -9 on Unix, killed by the Task Manager on Windows, "Force Quit" on Mac OS). Thus if your app crashes frequently, your users will lose disk space to multiple _MEIxxxxxx temporary folders.

Using a Console Window

By default the bootloader creates a command-line console (a terminal window in Linux and Mac OS, a command window in Windows). It gives this window to the Python interpreter for its standard input and output. Your script's use of print and input() are directed here. Error messages from Python and default logging output also appear in the console window.

An option for Windows and Mac OS is to tell PyInstaller to not provide a console window. The bootloader starts Python with no target for standard output or input. Do this when your script has a graphical interface for user input and can properly report its own diagnostics.

Hiding the Source Code

The bundled app does not include any source code. However, PyInstaller bundles compiled Python scripts (.pyc files). These could in principle be decompiled to reveal the logic of your code.

If you want to hide your source code more thoroughly, one possible option is to compile some of your modules with Cython. Using Cython you can convert Python modules into C and compile the C to machine language. PyInstaller can follow import statements that refer to Cython C object modules and bundle them.

Additionally, Python bytecode can be obfuscated with AES256 by specifying an encryption key on PyInstaller's command line. Please note that it is still very easy to extract the key and get back the original bytecode, but it should prevent most forms of "casual" tampering.

Options

Shortening the Command

Because of its numerous options, a full pyinstaller command can become very long. You will run the same command again and again as you develop your script. You can put the command in a shell script or batch file, using line continuations to make it readable. For example, in Linux:

pyinstaller --noconfirm --log-level=WARN \
    --onefile --nowindow \
    --hidden-import=secret1 \
    --hidden-import=secret2 \
    --upx-dir=/usr/local/share/ \
    myscript.spec

Or in Windows, use the little-known BAT file line continuation:

pyinstaller --noconfirm --log-level=WARN ^
    --onefile --nowindow ^
    --hidden-import=secret1 ^
    --hidden-import=secret2 ^
    --icon-file=..\MLNMFLCN.ICO ^
    myscript.spec

Using UPX

UPX is a free utility available for most operating systems. UPX compresses executable files and libraries, making them smaller, sometimes much smaller. UPX is available for most operating systems and can compress a large number of executable file formats. See the UPX home page for downloads, and for the list of supported executable formats. Development of UPX appears to have ended in September 2013, at which time it supported most executable formats except for 64-bit binaries for Mac OS X. UPX has no effect on those.

A compressed executable program is wrapped in UPX startup code that dynamically decompresses the program when the program is launched. After it has been decompressed, the program runs normally. In the case of a PyInstaller one-file executable that has been UPX-compressed, the full execution sequence is:

• The compressed program start up in the UPX decompressor code.
• After decompression, the program executes the PyInstaller bootloader, which creates a temporary environment for Python.
• The Python interpreter executes your script.

PyInstaller looks for UPX on the execution path or the path specified with the --upx-dir option. If UPX exists, PyInstaller applies it to the final executable, unless the --noupx option was given. UPX has been used with PyInstaller output often, usually with no problems.

Encrypting Python Bytecode

To encrypt the Python bytecode modules stored in the bundle, pass the --key=key-string argument on the command line.

For this to work, you must have the PyCrypto module installed. The key-string is a string of 16 characters which is used to encrypt each file of Python byte-code before it is stored in the archive inside the executable file.

Supporting Multiple Platforms

If you distribute your application for only one combination of OS and Python, just install PyInstaller like any other package and use it in your normal development setup.

cd ~/Dropbox/project_folder/src # Linux, Mac -- Windows similar
rm *.pyc # get rid of modules compiled by another Python
pyinstaller --workpath=path-to-local-temp-folder  \
            --distpath=path-to-local-dist-folder  \
            ...other options as required...       \
            ./myscript.py

Capturing Windows Version Data

A Windows app may require a Version resource file. A Version resource contains a group of data structures, some containing binary integers and some containing strings, that describe the properties of the executable. For details see the Microsoft Version Information Structures page.

Version resources are complex and some elements are optional, others required. When you view the version tab of a Properties dialog, there's no simple relationship between the data displayed and the structure of the resource. For this reason PyInstaller includes the pyi-grab_version command. It is invoked with the full path name of any Windows executable that has a Version resource:

pyi-grab_version executable_with_version_resource

The command writes text that represents a Version resource in readable form to standard output. You can copy it from the console window or redirect it to a file. Then you can edit the version information to adapt it to your program. Using pyi-grab_version you can find an executable that displays the kind of information you want, copy its resource data, and modify it to suit your package.

The version text file is encoded UTF-8 and may contain non-ASCII characters. (Unicode characters are allowed in Version resource string fields.) Be sure to edit and save the text file in UTF-8 unless you are certain it contains only ASCII string values.

Your edited version text file can be given with the --version-file= option to pyinstaller or pyi-makespec. The text data is converted to a Version resource and installed in the bundled app.

In a Version resource there are two 64-bit binary values, FileVersion and ProductVersion. In the version text file these are given as four-element tuples, for example:

filevers=(2, 0, 4, 0),
prodvers=(2, 0, 4, 0),

The elements of each tuple represent 16-bit values from most-significant to least-significant. For example the value (2, 0, 4, 0) resolves to 0002000000040000 in hex.

You can also install a Version resource from a text file after the bundled app has been created, using the set_version command:

set_version version_text_file executable_file

The set_version utility reads a version text file as written by pyi-grab_version, converts it to a Version resource, and installs that resource in the executable_file specified.

For advanced uses, examine a version text file as written by pyi-grab_version. You find it is Python code that creates a VSVersionInfo object. The class definition for VSVersionInfo is found in utils/win32/versioninfo.py in the PyInstaller distribution folder. You can write a program that imports versioninfo. In that program you can eval the contents of a version info text file to produce a VSVersionInfo object. You can use the .toRaw() method of that object to produce a Version resource in binary form. Or you can apply the unicode() function to the object to reproduce the version text file.

Building Mac OS X App Bundles

If you specify only --onefile under Mac OS X, the output in dist is a UNIX executable myscript. It can be executed from a Terminal command line. Standard input and output work as normal through the Terminal window.

If you also specify --windowed, the dist folder contains two outputs: the UNIX executable myscript and also an OS X application named myscript.app.

As you probably know, an application is a special type of folder. The one built by PyInstaller contains a folder always named Contents. It contains:

• A folder Frameworks which is empty.
• A folder MacOS that contains a copy of the same myscript UNIX executable.
• A folder Resources that contains an icon file.
• A file Info.plist that describes the app.

PyInstaller builds minimal versions of these elements.

Use the osx-bundle-identifier= argument to add a bundle identifier. This becomes the CFBundleIdentifier used in code-signing (see the PyInstaller code signing recipe and for more detail, the Apple code signing overview technical note).

Use the icon= argument to specify a custom icon for the application. (If you do not specify an icon file, PyInstaller supplies a file icon-windowed.icns with the PyInstaller logo.)

You can add items to the Info.plist by editing the spec file; see Spec File Options for a Mac OS X Bundle below.

Spec File Operation

After PyInstaller creates a spec file, or opens a spec file when one is given instead of a script, the pyinstaller command executes the spec file as code. Your bundled application is created by the execution of the spec file. The following is an shortened example of a spec file for a minimal, one-folder app:

block_cipher = None
a = Analysis(['minimal.py'],
     pathex=['/Developer/PItests/minimal'],
     binaries=None,
     datas=None,
     hiddenimports=[],
     hookspath=None,
     runtime_hooks=None,
     excludes=None,
     cipher=block_cipher)
pyz = PYZ(a.pure, a.zipped_data,
     cipher=block_cipher)
exe = EXE(pyz,... )
coll = COLLECT(...)

The statements in a spec file create instances of four classes, Analysis, PYZ, EXE and COLLECT.

• A new instance of class Analysis takes a list of script names as input. It analyzes all imports and other dependencies. The resulting object (assigned to a) contains lists of dependencies in class members named:
  • scripts: the python scripts named on the command line;
  • pure: pure python modules needed by the scripts;
  • binaries: non-python modules needed by the scripts;
  • datas: non-binary files included in the app.
• An instance of class PYZ is a .pyz archive (described under Inspecting Archives below), which contains all the Python modules from a.pure.
• An instance of EXE is built from the analyzed scripts and the PYZ archive. This object creates the executable file.
• An instance of COLLECT creates the output folder from all the other parts.

In one-file mode, there is no call to COLLECT, and the EXE instance receives all of the scripts, modules and binaries.

You modify the spec file to pass additional values to Analysis and to EXE.

Adding Files to the Bundle

To add files to the bundle, you create a list that describes the files and supply it to the Analysis call.

a = Analysis(...
     datas=[ ('src/README.txt', 'README') ],
     hiddenimports=...
     )

added_files = [
     ( 'src/README.txt', 'README' )
     ]
a = Analysis(...
     datas= added_files,
     ...
     )

added_files = [
         ( '/mygame/sfx/*.mp3', 'sfx' ),
         ( 'src/README.txt', 'README' )
         ]

a = Analysis(...
         binaries=[ ( '/usr/lib/libiodbc.2.dylib', 'libiodbc.dylib' ) ],
         ...

Giving Run-time Python Options

You can pass command-line options to the Python interpreter. The interpreter takes a number of command-line options but only the following are supported for a bundled app:

• v to write a message to stdout each time a module is initialized.
• u for unbuffered stdio.
• W and an option to change warning behavior: W ignore or W once or W error.

To pass one or more of these options, create a list of tuples, one for each option, and pass the list as an additional argument to the EXE call. Each tuple has three elements:

• The option as a string, for example v or W ignore.
• None
• The string OPTION

For example modify the spec file this way:

options = [ ('v', None, 'OPTION'), ('W ignore', None, 'OPTION') ]
a = Analysis( ...
            )
...
exe = EXE(pyz,
      a.scripts,
      options,   <--- added line
      exclude_binaries=...
      )

Spec File Options for a Mac OS X Bundle

When you build a windowed Mac OS X app (that is, running in Mac OS X, you specify the --onefile --windowed options), the spec file contains an additional statement to create the Mac OS X application bundle, or app folder:

app = BUNDLE(exe,
         name='myscript.app',
         icon=None,
         bundle_identifier=None)

The icon= argument to BUNDLE will have the path to an icon file that you specify using the --icon= option. The bundle_identifier will have the value you specify with the --osx-bundle-identifier= option.

An Info.plist file is an important part of a Mac OS X app bundle. (See the Apple bundle overview for a discussion of the contents of Info.plist.)

PyInstaller creates a minimal Info.plist. You can add or overwrite entries in the plist by passing an info_plist= parameter to the BUNDLE call. The value of this argument is a Python dict. Each key and value in the dict becomes a key and value in the Info.plist file. For example, when you use PyQt5, you can set NSHighResolutionCapable to True to let your app also work in retina screen:

app = BUNDLE(exe,
         name='myscript.app',
         icon=None,
         bundle_identifier=None
         info_plist={
            'NSHighResolutionCapable': 'True'
            },
         )

The info_plist= parameter only handles simple key:value pairs. It cannot handle nested XML arrays. For example, if you want to modify Info.plist to tell Mac OS X what filetypes your app supports, you must add a CFBundleDocumentTypes entry to Info.plist (see Apple document types). The value of that keyword is a list of dicts, each containing up to five key:value pairs.

To add such a value to your app's Info.plist you must edit the plist file separately after PyInstaller has created the app. However, when you re-run PyInstaller, your changes will be wiped out. One solution is to prepare a complete Info.plist file and copy it into the app after creating it.

Begin by building and testing the windowed app. When it works, copy the Info.plist prepared by PyInstaller. This includes the CFBundleExecutable value as well as the icon path and bundle identifier if you supplied them. Edit the Info.plist as necessary to add more items and save it separately.

From that point on, to rebuild the app call PyInstaller in a shell script, and follow it with a statement such as:

cp -f Info.plist dist/myscript.app/Contents/Info.plist

Multipackage Bundles

Some products are made of several different apps, each of which might depend on a common set of third-party libraries, or share code in other ways. When packaging such an product it would be a pity to treat each app in isolation, bundling it with all its dependencies, because that means storing duplicate copies of code and libraries.

You can use the multipackage feature to bundle a set of executable apps so that they share single copies of libraries. Each dependency (a DLL, for example) is packaged only once, in one of the apps. Any other apps in the set that depend on that DLL have an "external reference" to it, telling them to go find that dependency in the executable file of the app that contains it.

This saves disk space because each dependency is stored only once. However, to follow an external reference takes extra time when an app is starting up. Some of the apps in the set will have slightly slower launch times.

The external references between binaries include hard-coded paths to the output directory, and cannot be rearranged. If you use one-folder mode, you must install all the application folders within a single parent directory. If you use one-file mode, you must place all the related applications in the same directory when you install the application.

To build such a set of apps you must code a custom spec file that contains a call to the MERGE function. This function takes a list of analyzed scripts, finds their common dependencies, and modifies the analyses to minimize the storage cost.

The order of the analysis objects in the argument list matters. The MERGE function packages each dependency into the first script from left to right that needs that dependency. A script that comes later in the list and needs the same file will have an external reference to the prior script in the list. You might sequence the scripts to place the most-used scripts first in the list.

A custom spec file for a multipackage bundle contains one call to the MERGE function:

MERGE(*args)

MERGE is used after the analysis phase and before EXE and COLLECT. Its variable-length list of arguments consists of a list of tuples, each tuple having three elements:

• The first element is an Analysis object, an instance of class Analysis.
• The second element is the script name (without the .py extension).
• The third element is the name for the executable (usually the same as the script).

MERGE examines the Analysis objects to learn the dependencies of each script. It modifies these objects to avoid duplication of libraries and modules. As a result the packages generated will be connected.

foo_a = Analysis(['foo.py'],
        pathex=['/the/path/to/foo'],
        hiddenimports=[],
        hookspath=None)

bar_a = Analysis(['bar.py'], etc., etc...

zap_a = Analysis(['zap.py'], etc., etc...

MERGE( (foo_a, 'foo', 'foo'), (bar_a, 'bar', 'bar'), (zap_a, 'zap', 'zap') )

foo_pyz = PYZ(foo_a.pure)
foo_exe = EXE(foo_pyz, foo_a.scripts, ... etc.
foo_coll = COLLECT( foo_exe, foo_a.binaries, foo_a.datas... etc.

bar_pyz = PYZ(bar_a.pure)
bar_exe = EXE(bar_pyz, bar_a.scripts, ... etc.
bar_coll = COLLECT( bar_exe, bar_a.binaries, bar_a.datas... etc.

pyi-build foobarzap.spec

Recipes and Examples for Specific Problems

The PyInstaller FAQ page has work-arounds for some common problems. Code examples for some advanced uses and some common problems are available on our Recipe web-page. Some of the recipes there include:

• A more sophisticated way of collecting data files than the one shown above (Adding Files to the Bundle).
• Bundling a typical Django app.
• A use of a run-time hook to set the PyQt4 API level.
• A workaround for a multiprocessing constraint under Windows.

and others. Many of these Recipes were contributed by users. Please feel free to contribute more recipes!

Finding out What Went Wrong

Helping PyInstaller Find Modules

pyi-makespec --paths=/path/to/thisdir \
             --paths=/path/to/otherdir myscript.py

import django.core.management
def _find_commands(_):
    return """cleanup shell runfcgi runserver""".split()
django.core.management.find_commands = _find_commands

Getting the Latest Version

If you have some reason to think you have found a bug in PyInstaller you can try downloading the latest development version. This version might have fixes or features that are not yet at PyPI. Links to download the latest stable version and the latest development version are at PyInstaller.org.

If you have Git installed on your development system, you can use it together with pip to install the latest version of PyInstaller directly:

pip install -e git://github.com/pyinstaller/pyinstaller.git#egg=PyInstaller

Asking for Help

When none of the above suggestions help, do ask for assistance on the PyInstaller Email List.

Then, if you think it likely that you see a bug in PyInstaller, refer to the How to Report Bugs page.

The Bootstrap Process in Detail

There are many steps that must take place before the bundled script can begin execution. A summary of these steps was given in the Overview (How the One-Folder Program Works and How the One-File Program Works). Here is more detail to help you understand what the bootloader does and how to figure out problems.

The TOC and Tree Classes

PyInstaller manages lists of files using the TOC (Table Of Contents) class. It provides the Tree class as a convenient way to build a TOC from a folder path.

a.datas.append( [ ('README', 'src/README.txt', 'DATA' ) ] )
a.datas += [ ('README', 'src/README.txt', 'DATA' ) ]

a.binaries - [('badmodule', None, None)]

extras_toc = Tree('../src/extras', prefix='extras', excludes=['tmp','*.pyc'])

Inspecting Archives

An archive is a file that contains other files, for example a .tar file, a .jar file, or a .zip file. Two kinds of archives are used in PyInstaller. One is a ZlibArchive, which allows Python modules to be stored efficiently and, with some import hooks, imported directly. The other, a CArchive, is similar to a .zip file, a general way of packing up (and optionally compressing) arbitrary blobs of data. It gets its name from the fact that it can be manipulated easily from C as well as from Python. Both of these derive from a common base class, making it fairly easy to create new kinds of archives.

Inspecting Executables

You can inspect any executable file with pyi-bindepend:

pyi-bindepend executable_or_dynamic_library

The pyi-bindepend command analyzes the executable or DLL you name and writes to stdout all its binary dependencies. This is handy to find out which DLLs are required by an executable or by another DLL.

pyi-bindepend is used by PyInstaller to follow the chain of dependencies of binary extensions during Analysis.

Hooks in Detail

A hook is a module named hook- fully.qualified.import.name .py in the hooks folder of the PyInstaller folder (or in a folder specified with --additional-hooks-dir).

A hook is executable Python code that should define one or more of the following several global names:

excludedimports

A list of module names (relative or absolute) that the hooked module excludes in some opaque way. These names reduce the list of imported modules created by scanning the code. Example:

excludedimports = ['_proxy', 'utils', 'defs']

hiddenimports

A list of module names (relative or absolute) that the hooked module imports in some opaque way. These names extend the list of imported modules created by scanning the code. Example:

hiddenimports = ['_proxy', 'utils', 'defs']

A way to simplify adding all submodules of a package is to use:

from PyInstaller.utils.hooks import collect_submodules
hiddenimports = collect_submodules('package')

For an example see hook-docutils.py in the hooks folder.

Note: We suggest always using the fully qualified name PyInstaller.utils.hooks for importing hookutils. This avoids some pitfalls when implementing hooks for sub-modules.

datas

A list of globs of files or directories to bundle as datafiles. For each glob, a destination directory is specified.

Example:

datas = [
     ('/usr/share/icons/education_*.png', 'icons'),
     ('/usr/share/libsmi/mibs/*', 'mibs'),
     ]

This will copy all files matching education_*.png into the subdirectory icons, and recursively (because of the * wildcard) copy the content of /usr/share/libsmi/mibs into mibs.

A way to simplify collecting a folder of files is to use:

from PyInstaller.utils.hooks import collect_data_files
datas = collect_data_files('package_name')

to collect all package-related data files into a folder package_name in the app bundle. For an example see hook-pytz.py in the hooks folder.

binaries

A list of globs of files or directories to bundle as binaries. Binaries is a special case of datas in that PyInstaller will check if they depend on other possible dynamic libraries. Otherwise it looks the same.

Example:

binaries = [
     ('/usr/lib/lib*.so', 'libs'),
     ('C:\\Windows\\System32\\*.dll', 'dlls'),
     ]

attrs

A list of ( name , value ) pairs (where value is normally meaningless).

This will set the module-attribute name to value for each pair in the list. The value is usually unimportant because the modules are not executed.

The main purpose is so that ImportTracker will not issue spurious warnings when the rightmost node in a dotted name turns out to be an attribute in a package, instead of a missing submodule. For an example see the hook file hook-xml.sax.py.

def hook(mod):

Note

The need to use this should be rare. Instead, try to use the global names described above first. This will keep the hook's code simple.

Defines a function that takes a Module object. It must return a Module object, possibly the same one unchanged, or a modified one. A Module object is an instance of the class PyInstaller.depend.modules.Module() which you can read. If defined, hook(mod) is called before PyInstaller processed the global names described above.

This function is supported to handle cases like dynamic modification of a package's __path__ variable. A static list of names won't suffice because the new entry on __path__ may well require computation. See hook-win32com.py in the hooks folder for an example.

Development tools

On Debian/Ubuntu systems, you can run the following to install everything required:

sudo apt-get install build-essential

On Fedora/RHEL and derivates, you can run the following:

su
yum groupinstall "Development Tools"

On Mac OS X you can get gcc by installing Xcode. It is a suite of tools for developing software for Mac OS X. It can be also installed from your Mac OS X Install DVD. It is not necessary to install the version 4 of Xcode.

On Solaris and AIX the bootloader is tested with gcc.

On Windows you can use the Visual Studio C++ compiler (Visual Studio 2008 is recommended). A free version you can download is Visual Studio Express.

Note: There is no connection between the Visual Studio version used to compile the bootloader and the Visual Studio version used to compile Python. The bootloader is a self-contained static executable that imposes no restrictions on the version of Python being used. So you can use any Visual Studio version you have around.

You can download and install or unpack MinGW distribution from one of the following locations:

• MinGW - stable and mature, uses gcc 3.4 as its base
• MinGW-w64 - more recent, uses gcc 4.4 and up.
• TDM-GCC - MinGW and MinGW-w64 installers

Building for Windows

On Windows, when using MinGW, it is needed to add PATH_TO_MINGW\bin to your system PATH. variable. In command prompt before building bootloader run for example:

set PATH=C:\MinGW\bin;%PATH%

Change to the bootloader subdirectory. Run:

python ./waf configure build install

This will produce

• ./PyInstaller/bootloader/YOUR_OS/run,
• ./PyInstaller/bootloader/YOUR_OS/run_d
• ./PyInstaller/bootloader/YOUR_OS/runw and
• ./PyInstaller/bootloader/YOUR_OS/runw_d

which are the bootloaders.

On Windows this will produce in the ./PyInstaller/bootloader/YOUR_OS directory: run*.exe (bootloader for regular programs), and inprocsrvr*.dll (bootloader for in-process COM servers).

Note: If you have multiple versions of Python, the Python you use to run waf is the one whose configuration is used.

Note: On AIX the bootloader builds with gcc and is tested with gcc 4.2.0 on AIX 6.1.

Building for LINUX

By default, the bootloaders on Linux are LSB binaries.

LSB is a set of open standards that should increase compatibility among Linux distributions. PyInstaller produces a bootloader as an LSB binary in order to increase compatibility for packaged applications among distributions.

Note: LSB version 4.0 is required for successfull building of bootloader.

On Debian- and Ubuntu-based distros, you can install LSB 4.0 tools by adding the following repository to the sources.list file:

deb http://ftp.linux-foundation.org/pub/lsb/repositories/debian lsb-4.0 main

then after having update the apt repository:

sudo apt-get update

you can install LSB 4.0:

sudo apt-get install lsb lsb-build-cc

Most other distributions contain only LSB 3.0 in their software repositories and thus LSB build tools 4.0 must be downloaded by hand. From Linux Foundation download LSB sdk 4.0 for your architecture.

Unpack it by:

tar -xvzf lsb-sdk-4.0.3-1.ia32.tar.gz

To install it run:

cd lsb-sdk
./install.sh

After having installed the LSB tools, you can follow the standard building instructions.

NOTE: if for some reason you want to avoid LSB compilation, you can do so by specifying --no-lsb on the waf command line, as follows:

python waf configure --no-lsb build install

This will also produce support/loader/YOUR_OS/run, support/loader/YOUR_OS/run_d, support/loader/YOUR_OS/runw and support/loader/YOUR_OS/runw_d, but they will not be LSB binaries.