<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.10: http://docutils.sourceforge.net/" />
<title>PyInstaller Manual</title>
<meta name="author" content="William Caban (based on Gordon McMillan's manual)" />
<meta name="copyright" content="This document has been placed in the public domain." />
<link rel="stylesheet" href="stylesheets/default.css" type="text/css" />
</head>
<body>
<div class="document" id="pyinstaller-manual">
<h1 class="title">PyInstaller Manual</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>William Caban (based on Gordon McMillan's manual)</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference" href="mailto:william@hpcf.upr.edu">william@hpcf.upr.edu</a></td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>282</td></tr>
<tr class="field"><th class="docinfo-name">Source URL:</th><td class="field-body">svn://pyinstaller/branches/crypt/doc/source/Manual.rst</td>
</tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>This document has been placed in the public domain.</td></tr>
</tbody>
</table>
<div class="contents topic">
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#getting-started" id="id2" name="id2">Getting Started</a><ul>
<li><a class="reference" href="#installing-pyinstaller" id="id3" name="id3">Installing PyInstaller</a></li>
<li><a class="reference" href="#building-the-runtime-executables" id="id4" name="id4">Building the runtime executables</a></li>
<li><a class="reference" href="#configuring-your-pyinstaller-setup" id="id5" name="id5">Configuring your PyInstaller setup</a></li>
<li><a class="reference" href="#create-a-spec-file-for-your-project" id="id6" name="id6">Create a spec file for your project</a></li>
<li><a class="reference" href="#build-your-project" id="id7" name="id7">Build your project</a></li>
<li><a class="reference" href="#windows-com-server-support" id="id8" name="id8">Windows COM Server support</a></li>
<li><a class="reference" href="#building-optimized" id="id9" name="id9">Building Optimized</a></li>
<li><a class="reference" href="#a-note-on-using-upx" id="id10" name="id10">A Note on using UPX</a></li>
<li><a class="reference" href="#a-note-on-onefile" id="id11" name="id11">A Note on <tt class="docutils literal"><span class="pre">--onefile</span></tt></a></li>
<li><a class="reference" href="#a-note-on-egg-files-and-setuptools" id="id12" name="id12">A Note on .egg files and setuptools</a></li>
</ul>
</li>
<li><a class="reference" href="#pyinstaller-utilities" id="id13" name="id13">PyInstaller Utilities</a><ul>
<li><a class="reference" href="#archiveviewer" id="id14" name="id14">ArchiveViewer</a></li>
<li><a class="reference" href="#bindepend" id="id15" name="id15">bindepend</a></li>
<li><a class="reference" href="#grabversion-windows" id="id16" name="id16">GrabVersion (Windows)</a></li>
<li><a class="reference" href="#analyzing-dependencies" id="id17" name="id17">Analyzing Dependencies</a></li>
</ul>
</li>
<li><a class="reference" href="#spec-files" id="id18" name="id18">Spec Files</a><ul>
<li><a class="reference" href="#introduction" id="id19" name="id19">Introduction</a></li>
<li><a class="reference" href="#toc-class-table-of-contents" id="id20" name="id20">TOC Class (Table of Contents)</a></li>
<li><a class="reference" href="#target-subclasses" id="id21" name="id21">Target Subclasses</a><ul>
<li><a class="reference" href="#analysis" id="id22" name="id22">Analysis</a></li>
<li><a class="reference" href="#pyz" id="id23" name="id23">PYZ</a></li>
<li><a class="reference" href="#pkg" id="id24" name="id24">PKG</a></li>
<li><a class="reference" href="#exe" id="id25" name="id25">EXE</a></li>
<li><a class="reference" href="#dll" id="id26" name="id26">DLL</a></li>
<li><a class="reference" href="#collect" id="id27" name="id27">COLLECT</a></li>
<li><a class="reference" href="#tree" id="id28" name="id28">Tree</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference" href="#when-things-go-wrong" id="id29" name="id29">When Things Go Wrong</a><ul>
<li><a class="reference" href="#finding-out-what-went-wrong" id="id30" name="id30">Finding out What Went Wrong</a><ul>
<li><a class="reference" href="#buildtime-warnings" id="id31" name="id31">Buildtime Warnings</a></li>
<li><a class="reference" href="#getting-debug-messages" id="id32" name="id32">Getting Debug Messages</a></li>
<li><a class="reference" href="#getting-python-s-verbose-imports" id="id33" name="id33">Getting Python's Verbose Imports</a></li>
</ul>
</li>
<li><a class="reference" href="#helping-installer-find-modules" id="id34" name="id34">Helping Installer Find Modules</a><ul>
<li><a class="reference" href="#extending-the-path" id="id35" name="id35">Extending the Path</a></li>
<li><a class="reference" href="#listing-hidden-imports" id="id36" name="id36">Listing Hidden Imports</a></li>
<li><a class="reference" href="#extending-a-package-s-path" id="id37" name="id37">Extending a Package's <tt class="docutils literal"><span class="pre">__path__</span></tt></a></li>
<li><a class="reference" href="#changing-runtime-behavior" id="id38" name="id38">Changing Runtime Behavior</a></li>
<li><a class="reference" href="#adapting-to-being-frozen" id="id39" name="id39">Adapting to being "frozen"</a></li>
<li><a class="reference" href="#accessing-data-files" id="id40" name="id40">Accessing Data Files</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference" href="#miscellaneous" id="id41" name="id41">Miscellaneous</a><ul>
<li><a class="reference" href="#pmw-python-mega-widgets" id="id42" name="id42">Pmw -- Python Mega Widgets</a></li>
<li><a class="reference" href="#win9xpopen" id="id43" name="id43">Win9xpopen</a></li>
<li><a class="reference" href="#self-extracting-executables" id="id44" name="id44">Self-extracting executables</a><ul>
<li><a class="reference" href="#one-pass-execution" id="id45" name="id45">One Pass Execution</a></li>
<li><a class="reference" href="#two-pass-execution" id="id46" name="id46">Two Pass Execution</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference" href="#pyinstaller-archives" id="id47" name="id47">PyInstaller Archives</a><ul>
<li><a class="reference" href="#archives-introduction" id="id48" name="id48">Archives Introduction</a></li>
<li><a class="reference" href="#zlibarchive" id="id49" name="id49"><tt class="docutils literal"><span class="pre">ZlibArchive</span></tt></a></li>
<li><a class="reference" href="#carchive" id="id50" name="id50"><tt class="docutils literal"><span class="pre">CArchive</span></tt></a></li>
</ul>
</li>
<li><a class="reference" href="#license" id="id51" name="id51">License</a></li>
<li><a class="reference" href="#appendix" id="id52" name="id52">Appendix</a><ul>
<li><a class="reference" href="#mf-py-a-modulefinder-replacement" id="id53" name="id53"><tt class="docutils literal"><span class="pre">mf.py</span></tt>: A Modulefinder Replacement</a><ul>
<li><a class="reference" href="#importtracker" id="id54" name="id54">ImportTracker</a></li>
<li><a class="reference" href="#analyze-one" id="id55" name="id55"><tt class="docutils literal"><span class="pre">analyze_one()</span></tt></a></li>
<li><a class="reference" href="#module-classes" id="id56" name="id56">Module Classes</a></li>
<li><a class="reference" href="#code-scanning" id="id57" name="id57">code scanning</a></li>
<li><a class="reference" href="#hooks" id="id58" name="id58">Hooks</a></li>
<li><a class="reference" href="#warnings" id="id59" name="id59">Warnings</a></li>
<li><a class="reference" href="#cross-reference" id="id60" name="id60">Cross Reference</a></li>
<li><a class="reference" href="#usage" id="id61" name="id61">Usage</a></li>
</ul>
</li>
<li><a class="reference" href="#iu-py-an-imputil-replacement" id="id62" name="id62"><tt class="docutils literal"><span class="pre">iu.py</span></tt>: An <em>imputil</em> Replacement</a><ul>
<li><a class="reference" href="#importmanager" id="id63" name="id63"><tt class="docutils literal"><span class="pre">ImportManager</span></tt></a></li>
<li><a class="reference" href="#importdirector" id="id64" name="id64"><tt class="docutils literal"><span class="pre">ImportDirector</span></tt></a></li>
<li><a class="reference" href="#pathimportdirector" id="id65" name="id65"><tt class="docutils literal"><span class="pre">PathImportDirector</span></tt></a></li>
<li><a class="reference" href="#owner" id="id66" name="id66"><tt class="docutils literal"><span class="pre">Owner</span></tt></a></li>
<li><a class="reference" href="#packages" id="id67" name="id67">Packages</a></li>
<li><a class="reference" href="#possibilities" id="id68" name="id68">Possibilities</a></li>
<li><a class="reference" href="#compatibility" id="id69" name="id69">Compatibility</a></li>
<li><a class="reference" href="#performance" id="id70" name="id70">Performance</a></li>
<li><a class="reference" href="#limitations" id="id71" name="id71">Limitations</a></li>
<li><a class="reference" href="#id1" id="id72" name="id72">Usage</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id2" id="getting-started" name="getting-started">Getting Started</a></h1>
<div class="section">
<h2><a class="toc-backref" href="#id3" id="installing-pyinstaller" name="installing-pyinstaller">Installing PyInstaller</a></h2>
<p>First, unpack the archive on you path of choice. Installer is <strong>not</strong> a Python
package, so it doesn't need to go in site-packages, or have a .pth file. For
the purpose of this documentation we will assume /your/path/to/pyinstaller/. You will be
using a couple of scripts in the /your/path/to/pyinstaller/ directory, and these will find
everything they need from their own location. For convenience, keep the paths
to these scripts short (don't install in a deeply nested subdirectory).</p>
<p>PyInstaller is dependant to the version of python you configure it for. In
other words, you will need a separate copy of PyInstaller for each Python
version you wish to work with <em>or</em> you'll need to rerun <tt class="docutils literal"><span class="pre">Configure.py</span></tt> every
time you switch the Python version).</p>
<p><a class="reference" href="#pyinstaller-manual">Back to Top</a></p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id4" id="building-the-runtime-executables" name="building-the-runtime-executables">Building the runtime executables</a></h2>
<p><em>Note:</em> Windows users can skip this step, because all of Python is contained in
pythonXX.dll, and PyInstaller will use your pythonXX.dll.</p>
<p>On Linux the first thing to do is build the runtime executables.</p>
<p>Change to the /your/path/to/pyinstaller/ <tt class="docutils literal"><span class="pre">source/linux</span></tt> subdirectory. Run <tt class="docutils literal"><span class="pre">Make.py</span>
<span class="pre">[-n|-e]</span></tt> and then make. This will produce <tt class="docutils literal"><span class="pre">support/loader/run</span></tt> and
<tt class="docutils literal"><span class="pre">support/loader/run_d</span></tt>, which are the bootloaders.</p>
<div class="sidebar">
<p class="first sidebar-title">Bootloader</p>
<p class="last">The bootloader (also known as <em>stub</em> in literature) is the small program
which starts up your packaged program. Usually, the archive containing the
bytecoded modules of your program is simply attended to it. See
<a class="reference" href="#self-extracting-executables">Self-extracting executables</a> for more details on the process.</p>
</div>
<p><em>Note:</em> If you have multiple versions of Python, the Python you use to run
<tt class="docutils literal"><span class="pre">Make.py</span></tt> is the one whose configuration is used.</p>
<p>The <tt class="docutils literal"><span class="pre">-n</span></tt> and <tt class="docutils literal"><span class="pre">-e</span></tt> options set a non-elf or elf flag in your <tt class="docutils literal"><span class="pre">config.dat</span></tt>.
As of v1.0, the executable will try both strategies, and this flag
just sets how you want your executables built. In the elf strategy, the archive
is concatenated to the executable. In the non-elf strategy, the executable
expects an archive with the same name as itself in the executable's directory.
Note that the executable chases down symbolic links before determining it's name
and directory, so putting the archive in the same directory as the symbolic link
will not work.</p>
<p>Windows distributions come with several executables in the <tt class="docutils literal"><span class="pre">support/loader</span></tt>
directory: <tt class="docutils literal"><span class="pre">run_*.exe</span></tt> (bootloader for regular programs), and
<tt class="docutils literal"><span class="pre">inprocsrvr_*.dll</span></tt> (bootloader for in-process COM servers). To rebuild this,
you need to install <a class="reference" href="http://www.scons.org">Scons</a>, and then just run <tt class="docutils literal"><span class="pre">scons</span></tt> from the /your/path/to/pyinstaller/
directory.</p>
<p><a class="reference reference" href="#pyinstaller-manual">Back to Top</a></p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id5" id="configuring-your-pyinstaller-setup" name="configuring-your-pyinstaller-setup">Configuring your PyInstaller setup</a></h2>
<p>In the /your/path/to/pyinstaller/ directory, run <tt class="docutils literal"><span class="pre">Configure.py</span></tt>. This saves some
information into <tt class="docutils literal"><span class="pre">config.dat</span></tt> that would otherwise be recomputed every time.
It can be rerun at any time if your configuration changes. It must be run before
trying to build anything.</p>
<p><a class="reference reference reference" href="#pyinstaller-manual">Back to Top</a></p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id6" id="create-a-spec-file-for-your-project" name="create-a-spec-file-for-your-project">Create a spec file for your project</a></h2>
<p>[For Windows COM server support, see section <a class="reference" href="#windows-com-server-support">Windows COM Server Support</a>]</p>
<p>The root directory has a script Makespec.py for this purpose:</p>
<pre class="literal-block">
python Makespec.py [opts] <scriptname> [<scriptname> ...]
</pre>
<p>Where allowed OPTIONS are:</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">-F</span>, <span class="option">--onefile</span></kbd></td>
<td>produce a single file deployment (see below).</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-D</span>, <span class="option">--onedir</span></kbd></td>
<td>produce a single directory deployment (default).</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-K</span>, <span class="option">--tk</span></kbd></td>
<td>include TCL/TK in the deployment.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-a</span>, <span class="option">--ascii</span></kbd></td>
<td>do not include encodings. The default (on Python versions with unicode
support) is now to include all encodings.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-d</span>, <span class="option">--debug</span></kbd></td>
<td>use debug (verbose) versions of the executables.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-w</span>, <span class="option">--windowed</span>, <span class="option">--noconsole</span></kbd></td>
</tr>
<tr><td> </td><td>Use the Windows subsystem executable, which does not open
the console when the program is launched. <strong>(Windows only)</strong></td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-c</span>, <span class="option">--nowindowed</span>, <span class="option">--console</span></kbd></td>
</tr>
<tr><td> </td><td>Use the console subsystem executable. This is the default. <strong>(Windows only)</strong></td></tr>
<tr><td class="option-group">
<kbd><span class="option">-s</span>, <span class="option">--strip</span></kbd></td>
<td>the executable and all shared libraries will be run through strip. Note
that cygwin's strip tends to render normal Win32 dlls unusable.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-X</span>, <span class="option">--upx</span></kbd></td>
<td>if you have UPX installed (detected by Configure), this will use it to
compress your executable (and, on Windows, your dlls). See note below.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-o <var>DIR</var></span>, <span class="option">--out=<var>DIR</var></span></kbd></td>
</tr>
<tr><td> </td><td>create the spec file in <em>directory</em>. If not specified, and the current
directory is Installer's root directory, an output subdirectory will be
created. Otherwise the current directory is used.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-p <var>DIR</var></span>, <span class="option">--paths=<var>DIR</var></span></kbd></td>
</tr>
<tr><td> </td><td>set base path for import (like using PYTHONPATH). Multiple directories are
allowed, separating them with the path separator (';' under Windows, ':'
under Linux), or using this option multiple times.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--icon=<var><FILE.ICO></var></span></kbd></td>
</tr>
<tr><td> </td><td>add <em>file.ico</em> to the executable's resources. <strong>(Windows only)</strong></td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--icon=<var><FILE.EXE,N></var></span></kbd></td>
</tr>
<tr><td> </td><td>add the <em>n</em>-th incon in <em>file.exe</em> to the executable's resources. <strong>(Windows
only)</strong></td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-v <var>FILE</var></span>, <span class="option">--version=<var>FILE</var></span></kbd></td>
</tr>
<tr><td> </td><td>add verfile as a version resource to the executable. <strong>(Windows only)</strong></td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">-n <var>NAME</var></span>, <span class="option">--name=<var>NAME</var></span></kbd></td>
</tr>
<tr><td> </td><td>optional <em>name</em> to assign to the project (from which the spec file name is
generated). If omitted, the basename of the (first) script is used.</td></tr>
</tbody>
</table>
<p>[For building with optimization on (like <tt class="docutils literal"><span class="pre">Python</span> <span class="pre">-O</span></tt>), see section
<a class="reference" href="#building-optimized">Building Optimized</a>]</p>
<p>For simple projects, the generated spec file will probably be sufficient. For
more complex projects, it should be regarded as a template. The spec file is
actually Python code, and modifying it should be ease. See <a class="reference" href="#spec-files">Spec Files</a> for
details.</p>
<p><a class="reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id7" id="build-your-project" name="build-your-project">Build your project</a></h2>
<pre class="literal-block">
python Build.py specfile
</pre>
<p>A <tt class="docutils literal"><span class="pre">buildproject</span></tt> subdirectory will be created in the specfile's directory. This
is a private workspace so that <tt class="docutils literal"><span class="pre">Build.py</span></tt> can act like a makefile. Any named
targets will appear in the specfile's directory. For <tt class="docutils literal"><span class="pre">--onedir</span></tt>
configurations, it will create also <tt class="docutils literal"><span class="pre">distproject</span></tt>, which is the directory you're
interested in. For a <tt class="docutils literal"><span class="pre">--onefile</span></tt>, the executable will be in the specfile's
directory.</p>
<p>In most cases, this will be all you have to do. If not, see <a class="reference" href="#when-things-go-wrong">When things go
wrong</a> and be sure to read the introduction to <a class="reference" href="#spec-files">Spec Files</a>.</p>
<p><a class="reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id8" id="windows-com-server-support" name="windows-com-server-support">Windows COM Server support</a></h2>
<p>For Windows COM support execute:</p>
<pre class="literal-block">
python MakeCOMServer.py [OPTION] script...
</pre>
<p>This will generate a new script <tt class="docutils literal"><span class="pre">drivescript.py</span></tt> and a spec file for the script.</p>
<p>These options are allowed:</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">--debug</span></kbd></td>
<td>Use the verbose version of the executable.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--verbose</span></kbd></td>
<td>Register the COM server(s) with the quiet flag off.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--ascii</span></kbd></td>
<td>do not include encodings (this is passed through to Makespec).</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--out <var><dir></var></span></kbd></td>
<td>Generate the driver script and spec file in dir.</td></tr>
</tbody>
</table>
<p>Now <a class="reference" href="#build-your-project">Build your project</a> on the generated spec file.</p>
<p>If you have the win32dbg package installed, you can use it with the generated
COM server. In the driver script, set <tt class="docutils literal"><span class="pre">debug=1</span></tt> in the registration line.</p>
<p><strong>Warnings</strong>: the inprocess COM server support will not work when the client
process already has Python loaded. It would be rather tricky to
non-obtrusively hook into an already running Python, but the show-stopper is
that the Python/C API won't let us find out which interpreter instance I should
hook into. (If this is important to you, you might experiment with using
apartment threading, which seems the best possibility to get this to work). To
use a "frozen" COM server from a Python process, you'll have to load it as an
exe:</p>
<pre class="literal-block">
o = win32com.client.Dispatch(progid,
clsctx=pythoncom.CLSCTX_LOCAL_SERVER)
</pre>
<p>MakeCOMServer also assumes that your top level code (registration etc.) is
"normal". If it's not, you will have to edit the generated script.</p>
<p><a class="reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id9" id="building-optimized" name="building-optimized">Building Optimized</a></h2>
<p>There are two facets to running optimized: gathering <tt class="docutils literal"><span class="pre">.pyo</span></tt>'s, and setting the
<tt class="docutils literal"><span class="pre">Py_OptimizeFlag</span></tt>. Installer will gather <tt class="docutils literal"><span class="pre">.pyo</span></tt>'s if it is run optimized:</p>
<pre class="literal-block">
python -O Build.py ...
</pre>
<p>The <tt class="docutils literal"><span class="pre">Py_OptimizeFlag</span></tt> will be set if you use a <tt class="docutils literal"><span class="pre">('O','','OPTION')</span></tt> in one of
the <tt class="docutils literal"><span class="pre">TOCs</span></tt> building the <tt class="docutils literal"><span class="pre">EXE</span></tt>:</p>
<pre class="literal-block">
exe = EXE(pyz,
a.scripts + [('O','','OPTION')],
...
</pre>
<p>See <a class="reference" href="#spec-files">Spec Files</a> for details.</p>
<p><a class="reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id10" id="a-note-on-using-upx" name="a-note-on-using-upx">A Note on using UPX</a></h2>
<p>On both Windows and Linux, UPX can give truly startling compression - the days
of fitting something useful on a diskette are not gone forever! Installer has
been tested with many UPX versions without problems. Just get it and install it
on your PATH, then rerun configure.</p>
<p>For Windows, there is a problem of compatibility between UPX and executables
generated by Microsoft Visual Studio .NET 2003 (or the equivalent free
toolkit available for download). This is especially worrisome for users of
Python 2.4+, where most extensions (and Python itself) are compiled with that
compiler. This issue has been fixed in later beta versions of UPX, so you
will need at least UPX 1.92 beta. <a class="reference" href="#configuring-your-pyinstaller-setup">Configure.py</a> will check this for you
and complain if you have an older version of UPX and you are using Python 2.4.</p>
<div class="sidebar">
<p class="first sidebar-title">UPX and Unix</p>
<p class="last">Under UNIX, old versions of UPX were not able to expand and execute the
executable in memory, and they were extracting it into a temporary file
in the filesystem, before spawning it. This is no longer valid under Linux,
but the information in this paragraph still needs to be updated.</p>
</div>
<p>For Linux, a bit more discussion is in order. First, UPX is only useful on
executables, not shared libs. Installer accounts for that, but to get the full
benefit, you might rebuild Python with more things statically linked.</p>
<p>More importantly, when <tt class="docutils literal"><span class="pre">run</span></tt> finds that its <tt class="docutils literal"><span class="pre">sys.argv[0]</span></tt> does not contain a path,
it will use <tt class="docutils literal"><span class="pre">/proc/pid/exe</span></tt> to find itself (if it can). This happens, for
example, when executed by Apache. If it has been upx-ed, this symbolic link
points to the tempfile created by the upx stub and PyInstaller will fail (please
see the UPX docs for more information). So for now, at least, you can't use upx
for CGI's executed by Apache. Otherwise, you can ignore the warnings in the UPX
docs, since what PyInstaller opens is the executable Installer created, not the
temporary upx-created executable.</p>
<p><a class="reference reference reference reference reference reference reference reference" href="#pyinstaller-manual">Back to Top</a></p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id11" id="a-note-on-onefile" name="a-note-on-onefile">A Note on <tt class="docutils literal docutils literal"><span class="pre">--onefile</span></tt>