Docs » Using PyInstaller

U P I
The syntax of the pyinstaller command is:

pyinstaller [op ons] script [script …] | specfile

In the most simple case, set the current directory to the loca on of your program
myscript.py and execute:

pyinstaller myscript.py

PyInstaller analyzes myscript.py and:

Writes myscript.spec in the same folder as the script.

Creates a folder build in the same folder as the script if it does not exist.
Writes some log files and working files in the build folder.
Creates a folder dist in the same folder as the script if it does not exist.
Writes the myscript executable folder in the dist folder.

In the dist folder you find the bundled app you distribute to your users.

Normally you name one script on the command line. If you name more, all are analyzed and
included in the output. However, the first script named supplies the name for the spec file
and for the executable folder or file. Its code is the first to execute at run- me.

For certain uses you may edit the contents of myscript.spec (described under Using Spec
Files). A er you do this, you name the spec file to PyInstaller instead of the script:

pyinstaller myscript.spec

The myscript.spec file contains most of the informa on provided by the op ons that were
specified when pyinstaller (or pyi-makespec) was run with the script file as the argument. You
typically do not need to specify any op ons when running pyinstaller with the spec file. Only
a few command-line op ons have an effect when building from a spec file.

You may give a path to the script or spec file, for example

pyinstaller op ons… ~/myproject/source/myscript.py

/
 or, on Windows,

pyinstaller "C:\Documents and Settings\project\myscript.spec"

Options

General Options
-h, --
show this help message and exit
help

-v, --
Show program version info and exit.
version

--
distpath Where to put the bundled app (default: ./dist)
DIR

--workpath WORKPATH

Where to put all the temporary work files, .log, .pyz and etc. (default:
./build)

-y, --noconfirm

Replace output directory (default: SPECPATH/dist/SPECNAME) without

asking for confirma on

--upx-dir UPX_DIR

Path to UPX u lity (default: search the execu on path)

-a, --
Do not include unicode encoding support (default: included if available)
ascii

--clean Clean PyInstaller cache and remove temporary files before building.

--log-level LEVEL

Amount of detail in build- me console messages. LEVEL may be one of

TRACE, DEBUG, INFO, WARN, ERROR, CRITICAL (default: INFO).

What to generate
-D, --
Create a one-folder bundle containing an executable (default)
onedir

-F, --
Create a one-file bundled executable.
onefile

--specpath
Folder to store the generated spec file (default: current directory)
DIR

-n NAME, --name NAME

/
 Name to assign to the bundled app and spec file (default: first
script’s basename)

What to bundle, where to search

--add-data <SRC;DEST or SRC:DEST>

Addi onal non-binary files or folders to be added to the executable. The path
separator is pla orm specific, os.pathsep (which is ; on Windows and : on
most unix systems) is used. This op on can be used mul ple mes.

--add-binary <SRC;DEST or SRC:DEST>

Addi onal binary files to be added to the executable. See the --add-data
op on for more details. This op on can be used mul ple mes.

-p DIR, --paths DIR

A path to search for imports (like using PYTHONPATH). Mul ple paths are
allowed, separated by ‘:’, or use this op on mul ple mes

--hidden-import MODULENAME, --hiddenimport MODULENAME

Name an import not visible in the code of the script(s). This op on can be used
mul ple mes.

--additional-hooks-dir HOOKSPATH

An addi onal path to search for hooks. This op on can be used mul ple mes.

--runtime-hook RUNTIME_HOOKS

Path to a custom run me hook file. A run me hook is code that is bundled
with the executable and is executed before any other code or module to set up
special features of the run me environment. This op on can be used mul ple
mes.

--exclude-module EXCLUDES

Op onal module or package (the Python name, not the path name) that will be
ignored (as though it was not found). This op on can be used mul ple mes.

--
key The key used to encrypt Python bytecode.
KEY

How to generate

-d <all,imports,bootloader,noarchive>, --debug
<all,imports,bootloader,noarchive>

/
 Provide assistance with debugging a frozen applica on. This
argument may be provided mul ple mes to select several of the
following op ons.

all: All three of the following op ons.

imports: specify the -v op on to the underlying Python interpreter,
causing it to print a message each me a module is ini alized, showing
the place (filename or built-in module) from which it is loaded. See
h ps://docs.python.org/3/using/cmdline.html#id4.
bootloader: tell the bootloader to issue progress messages while
ini alizing and star ng the bundled app. Used to diagnose problems
with missing imports.
noarchive: instead of storing all frozen Python source files as an archive
inside the resul ng executable, store them as files in the resul ng output
directory.

-s, -
Apply a symbol-table strip to the executable and shared libs (not
-
recommended for Windows)
strip

-- Do not use UPX even if it is available (works differently between Windows

noupx and *nix)

--upx-exclude FILE

Prevent a binary from being compressed when using upx. This is typically
used if upx corrupts certain binaries during compression. FILE is the
filename of the binary without path. This op on can be used mul ple mes.

Windows and Mac OS X specific options

-c, --console, --nowindowed

Open a console window for standard i/o (default). On Windows this op on will
have no effect if the first script is a ‘.pyw’ file.

-w, --windowed, --noconsole

Windows and Mac OS X: do not provide a console window for standard i/o. On
Mac OS X this also triggers building an OS X .app bundle. On Windows this op on
will be set if the first script is a ‘.pyw’ file. This op on is ignored in *NIX systems.

-i <FILE.ico or FILE.exe,ID or FILE.icns>, --icon <FILE.ico or

FILE.exe,ID or FILE.icns>

FILE.ico: apply that icon to a Windows executable. FILE.exe,ID, extract the icon
with ID from an exe. FILE.icns: apply the icon to the .app bundle on Mac OS X

Windows specific options

--version-file FILE

/
 add a version resource from FILE to the exe

-m <FILE or XML>, --manifest <FILE or XML>

add manifest FILE or XML to the exe

-r RESOURCE, --resource RESOURCE

Add or update a resource to a Windows executable. The RESOURCE is

one to four items, FILE[,TYPE[,NAME[,LANGUAGE]]]. FILE can be a data
file or an exe/dll. For data files, at least TYPE and NAME must be
specified. LANGUAGE defaults to 0 or may be specified as wildcard * to
update all resources of the given TYPE and NAME. For exe/dll files, all
resources from FILE will be added/updated to the final executable if
TYPE, NAME and LANGUAGE are omi ed or specified as wildcard *.This
op on can be used mul ple mes.

--uac- Using this op on creates a Manifest which will request eleva on upon
admin applica on restart.

--uac- Using this op on allows an elevated applica on to work with Remote

uiaccess Desktop.

Windows Side-by-side Assembly searching options (advanced)

--win-private-assemblies

Any Shared Assemblies bundled into the applica on will be changed into Private
Assemblies. This means the exact versions of these assemblies will always be
used, and any newer versions installed on user machines at the system level will
be ignored.

--win-no-prefer-redirects

While searching for Shared or Private Assemblies to bundle into the applica on,
PyInstaller will prefer not to follow policies that redirect to newer versions, and
will try to bundle the exact versions of the assembly.

Mac OS X specific options

--osx-bundle-identifier BUNDLE_IDENTIFIER

Mac OS X .app bundle iden fier is used as the default unique program name for
code signing purposes. The usual form is a hierarchical name in reverse DNS
nota on. For example: com.mycompany.department.appname (default: first
script’s basename)

Rarely used special options

--runtime-tmpdir PATH

Where to extract libraries and support files in onefile-mode. If this op on is given,

the bootloader will ignore any temp-folder loca on defined by the run- me OS.
The _MEIxxxxxx -folder will be created here. Please use this op on only if you
know what you are doing.
/
 --bootloader-ignore-signals

Tell the bootloader to ignore signals rather than forwarding them to the child
process. Useful in situa ons where e.g. a supervisor process signals both the
bootloader and child (e.g. via a process group) to avoid signalling the child twice.

Shortening the Command

Because of its numerous op ons, 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 con nua ons to make it readable. For example, in
GNU/Linux:

pyinstaller --noconfirm --log-level=WARN \

--onefile --nowindow \
--add-data="README:." \
--add-data="image1.png:img" \
--add-binary="libfoo.so:lib" \
--hidden-import=secret1 \
--hidden-import=secret2 \
--upx-dir=/usr/local/share/ \
myscript.spec

Or in Windows, use the li le-known BAT file line con nua on:

pyinstaller --noconfirm --log-level=WARN ^

--onefile --nowindow ^
--add-data="README;." ^
--add-data="image1.png;img" ^
--add-binary="libfoo.so;lib" ^
--hidden-import=secret1 ^
--hidden-import=secret2 ^
--icon=..\MLNMFLCN.ICO ^
myscript.spec

Running PyInstaller from Python code

If you want to run PyInstaller from within Python code use the run func on of the __main__

module and pass all command line arguments in as a list, e.g.

/
 import PyInstaller.__main__

PyInstaller.__main__.run([
'--name=%s' % package_name,
'--onefile',
'--windowed',
'--add-binary=%s' % os.path.join('resource', 'path', '*.png'),
'--add-data=%s' % os.path.join('resource', 'path', '*.txt'),
'--icon=%s' % os.path.join('resource', 'path', 'icon.ico'),
os.path.join('my_package', '__main__.py'),
])

Running PyInstaller with Python optimizations

 Note:

When using this feature, you should be aware of how the Python bytecode op miza on
mechanism works. When using -O , __debug__ is set to False and assert statements are
removed from the bytecode. The -OO flag addi onally removes docstrings.

Using this feature affects not only your main script, but all modules included by
PyInstaller. If your code (or any module imported by your script) relies on these features,
your program may break or have unexpected behavior.

PyInstaller can be run with Python op miza on flags ( -O or -OO ) by execu ng it as a Python
module, rather than using the pyinstaller command:

# run with basic optimizations

python -O -m PyInstaller myscript.py

# also discard docstrings

python -OO -m PyInstaller myscript.py

Or, by explicitly se ng the PYTHONOPTIMIZE environment variable to a non-zero value:

# Unix
PYTHONOPTIMIZE=1 pyinstaller myscript.py

# Windows
set PYTHONOPTIMIZE=1 && pyinstaller myscript.py

You can use any PyInstaller op ons that are otherwise available with the pyinstaller

command. For example:

python -O -m PyInstaller --onefile myscript.py

/
Alterna vely, you can also use the path to pyinstaller:

python -O /path/to/pyinstaller myscript.py

Using UPX
UPX is a free u lity available for most opera ng systems. UPX compresses executable files
and libraries, making them smaller, some mes much smaller. UPX is available for most
opera ng 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.

A compressed executable program is wrapped in UPX startup code that dynamically

decompresses the program when the program is launched. A er it has been decompressed,
the program runs normally. In the case of a PyInstaller one-file executable that has been UPX-
compressed, the full execu on sequence is:

The compressed program start up in the UPX decompressor code.

A er 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 execu on path or the path specified with the --upx-dir

op on. If UPX exists, PyInstaller applies it to the final executable, unless the --noupx op on
was given. UPX has been used with PyInstaller output o en, 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 need to run:

pip install pyinstaller[encryption]

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.

This feature uses the nyaes module internally for the encryp on.

Defining the Extraction Location /

 In rare cases, when you bundle to a single executable (see Bundling to One File and How the
One-File Program Works), you may want to control the loca on of the temporary directory at
compile me. This can be done using the --runtime-tmpdir op on. If this op on is given, the
bootloader will ignore any temp-folder loca on defined by the run- me OS. Please use this
op on only if you know what you are doing.

Supporting Multiple Platforms

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

Supporting Multiple Python Environments

When you need to bundle your applica on within one OS but for different versions of
Python and support libraries – for example, a Python 3.6 version and a Python 3.7 version; or
a supported version that uses Qt4 and a development version that uses Qt5 – we
recommend you use venv. With venv you can maintain different combina ons of Python and
installed packages, and switch from one combina on to another easily. These are called
virtual nvironments or venvs in short.

Use venv to create as many different development environments as you need, each with
its unique combina on of Python and installed packages.
Install PyInstaller in each virtual environment.
Use PyInstaller to build your applica on in each virtual environment.

Note that when using venv, the path to the PyInstaller commands is:

Windows: ENV_ROOT\Scripts
Others: ENV_ROOT/bin

Under Windows, the pip-Win package makes it especially easy to set up different
environments and switch between them. Under GNU/Linux and Mac OS, you switch
environments at the command line.

See PEP 405 and the official Python Tutorial on Virtual Environments and Packages for more
informa on about Python virtual environments.

Supporting Multiple Operating Systems

If you need to distribute your applica on for more than one OS, for example both Windows
and Mac OS X, you must install PyInstaller on each pla orm and bundle your app separately
on each.

/
You can do this from a single machine using virtualiza on. The free virtualBox or the paid
VMWare and Parallels allow you to run another complete opera ng system as a “guest”. You
set up a virtual machine for each “guest” OS. In it you install Python, the support packages
your applica on needs, and PyInstaller.

A File Sync & Share system like NextCloud is useful with virtual machines. Install the
synchroniza on client in each virtual machine, all linked to your synchroniza on account.
Keep a single copy of your script(s) in a synchronized folder. Then on any virtual machine you
can run PyInstaller thus:

cd ~/NextCloud/project_folder/src # GNU/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

PyInstaller reads scripts from the common synchronized folder, but writes its work files and
the bundled app in folders that are local to the virtual machine.

If you share the same home directory on mul ple pla orms, for example GNU/Linux and OS
X, you will need to set the PYINSTALLER_CONFIG_DIR environment variable to different
values on each pla orm otherwise PyInstaller may cache files for one pla orm and use them
on the other pla orm, as by default it uses a subdirectory of your home directory as its cache
loca on.

It is said to be possible to cross-develop for Windows under GNU/Linux using the free Wine
environment. Further details are needed, see How to Contribute.

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 proper es of the executable. For details see the Microso Version Informa on Structures
page.

Version resources are complex and some elements are op onal, others required. When you
view the version tab of a Proper es dialog, there’s no simple rela onship 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 informa on to adapt it to your program. Using pyi-grab_version you can find an
executable that displays the kind of informa on 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= op on 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 a er the bundled app has been
created, using the pyi-set_version command:

pyi-set_version version_text_file executable_file

The pyi-set_version u lity reads a version text file as wri en 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 wri en by pyi-grab_version . You find it is
Python code that creates a VSVersionInfo object. The class defini on for VSVersionInfo is
found in utils/win32/versioninfo.py in the PyInstaller distribu on 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() func on
to the object to reproduce the version text file.

Building Mac OS X App Bundles

/
 Under Mac OS X, PyInstaller always builds a UNIX executable in dist . If you specify
--onedir , the output is a folder named myscript containing suppor ng files and an
executable named myscript . If you specify --onefile , the output is a single UNIX executable
named myscript . Either executable can be started from a Terminal command line. Standard
input and output work as normal through that Terminal window.

If you specify --windowed with either op on, the dist folder also contains an OS X
applica on named myscript.app .

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

A folder Frameworks which is empty.

A folder Resources that contains an icon file.
A file Info.plist that describes the app.
A folder MacOS that contains the the executable and suppor ng files, just as in the
--onedir folder.

Use the icon= argument to specify a custom icon for the applica on. It will be copied into
the Resources folder. (If you do not specify an icon file, PyInstaller supplies a file
icon-windowed.icns with the PyInstaller logo.)

Use the osx-bundle-identifier= argument to add a bundle iden fier. 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).

You can add other items to the Info.plist by edi ng the spec file; see Spec File Op ons for
a Mac OS X Bundle below.

Platform-specific Notes

GNU/Linux

Making GNU/Linux Apps Forward-Compatible

Under GNU/Linux, PyInstaller does not bundle libc (the C standard library, usually glibc ,
the Gnu version) with the app. Instead, the app expects to link dynamically to the libc from
the local OS where it runs. The interface between any app and libc is forward compa ble to
newer releases, but it is not backward compa ble to older releases.

For this reason, if you bundle your app on the current version of GNU/Linux, it may fail to
execute (typically with a run me dynamic link error) if it is executed on an older version of
GNU/Linux.

/
 The solu on is to always build your app on the oldest version of GNU/Linux you mean to
support. It should con nue to work with the libc found on newer versions.

The GNU/Linux standard libraries such as glibc are distributed in 64-bit and 32-bit versions,
and these are not compa ble. As a result you cannot bundle your app on a 32-bit system and
run it on a 64-bit installa on, nor vice-versa. You must make a unique version of the app for
each word-length supported.

Windows
For Python >= 3.5 targe ng Windows < 10, the developer needs to take special care to
include the Visual C++ run- me .dlls: Python 3.5 uses Visual Studio 2015 run- me, which has
been renamed into “Universal CRT“ and has become part of Windows 10. For Windows Vista
through Windows 8.1 there are Windows Update packages, which may or may not be
installed in the target-system. So you have the following op ons:

1. Build on Windows 7 which has been reported to work.

2. Include one of the VCRedist packages (the redistributable package files) into your
applica on’s installer. This is Microso ’s recommended way, see “Distribu ng So ware
that uses the Universal CRT“ in the above-men oned link, numbers 2 and 3.
3. Install the Windows So ware Development Kit (SDK) for Windows 10 and expand the
.spec-file to include the required DLLs, see “Distribu ng So ware that uses the Universal
CRT“ in the above-men oned link, number 6.

If you think, PyInstaller should do this by itself, please help improving PyInstaller.

Mac OS X

Making Mac OS X apps Forward-Compatible

In Mac OS X, components from one version of the OS are usually compa ble with later
versions, but they may not work with earlier versions.

The only way to be certain your app supports an older version of Mac OS X is to run
PyInstaller in the oldest version of the OS you need to support.

For example, to be sure of compa bility with “Snow Leopard” (10.6) and later versions, you
should execute PyInstaller in that environment. You would create a copy of Mac OS X 10.6,
typically in a virtual machine. In it, install the desired level of Python (the default Python in
Snow Leopard was 2.6, which PyInstaller no longer supports), and install PyInstaller, your
source, and all its dependencies. Then build your app in that environment. It should be
compa ble with later versions of Mac OS X.

Building 32-bit Apps in Mac OS X

 Note:
/
 This sec on s ll refers to Python 2.7 provided by Apple. It might not be valid for Python 3
installed from MacPorts or Homebrew.

Please contribute to keep this sec on up-to-date.

Older versions of Mac OS X supported both 32-bit and 64-bit executables. PyInstaller builds
an app using the the word-length of the Python used to execute it. That will typically be a
64-bit version of Python, resul ng in a 64-bit executable. To create a 32-bit executable, run
PyInstaller under a 32-bit Python.

Python as installed in OS X will usually be executable in either 64- or 32-bit mode. To verify
this, apply the file command to the Python executable:

$ file /usr/local/bin/python3
/usr/local/bin/python3: Mach-O universal binary with 2 architectures
/usr/local/bin/python3 (for architecture i386): Mach-O executable i386
/usr/local/bin/python3 (for architecture x86_64): Mach-O 64-bit executable x86_64

The OS chooses which architecture to run, and typically defaults to 64-bit. You can force the
use of either architecture by name using the arch command:

$ /usr/local/bin/python3
Python 3.4.2 (v3.4.2:ab2c023a9432, Oct 5 2014, 20:42:22)
[GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys; sys.maxsize
9223372036854775807

$ arch -i386 /usr/local/bin/python3

Python 3.4.2 (v3.4.2:ab2c023a9432, Oct 5 2014, 20:42:22)
[GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys; sys.maxsize
2147483647

Apple’s default /usr/bin/python may circumvent the arch specifica on and run 64-bit
regardless. (That is not the case if you apply arch to a specific version such as
/usr/bin/python2.7 .) To make sure of running 32-bit in all cases, set the following
environment variable:

VERSIONER_PYTHON_PREFER_32_BIT=yes
arch -i386 /usr/bin/python pyinstaller --clean -F -w myscript.py

Getting the Opened Document Names

/
  Note:

Support for OpenDocument events is broken in PyInstaller 3.0 owing to code changes
needed in the bootloader to support current versions of Mac OS X. Do not a empt to use
this feature un l it has been fixed. If this feature is important to you, follow and comment
on the status of PyInstaller Issue #1309.

When a user double-clicks a document of a type your applica on supports, or when a user
drags a document icon and drops it on your applica on’s icon, Mac OS X launches your
applica on and provides the name(s) of the opened document(s) in the form of an
OpenDocument AppleEvent. This AppleEvent is received by the bootloader before your code
has started execu ng.

The bootloader gets the names of opened documents from the OpenDocument event and
encodes them into the argv string before star ng your code. Thus your code can query
sys.argv to get the names of documents that should be opened at startup.

OpenDocument is the only AppleEvent the bootloader handles. If you want to handle other
events, or events that are delivered a er the program has launched, you must set up the
appropriate handlers.

AIX
Depending on whether Python was build as a 32-bit or a 64-bit executable you may need to
set or unset the environment variable OBJECT_MODE . To determine the size the following
command can be used:

$ python -c "import sys; print(sys.maxsize) <= 2**32"

True

When the answer is True (as above) Python was build as a 32-bit executable.

When working with a 32-bit Python executable proceed as follows:

$ unset OBJECT_MODE
$ pyinstaller <your arguments>

When working with a 64-bit Python executable proceed as follows:

$ export OBJECT_MODE=64
$ pyinstaller <your arguments>

/
/