Pyinstaller build for windows

Positional Arguments

scriptname

Name of scriptfiles to be processed or exactly one
.spec file. If a .spec file is specified, most options
are unnecessary and are ignored.

Options

-h, —help

show this help message and exit

-v, —version

Show program version info and exit.

—distpath DIR

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

—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
confirmation

—upx-dir UPX_DIR

Path to UPX utility (default: search the execution
path)

—clean

Clean PyInstaller cache and remove temporary files
before building.

—log-level LEVEL

Amount of detail in build-time console messages. LEVEL
may be one of TRACE, DEBUG, INFO, WARN, DEPRECATION,
ERROR, FATAL (default: INFO). Also settable via and
overrides the PYI_LOG_LEVEL environment variable.

What To Generate

-D, —onedir

Create a one-folder bundle containing an executable
(default)

-F, —onefile

Create a one-file bundled executable.

—specpath DIR

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

-n, —name NAME

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

—contents-directory CONTENTS_DIRECTORY

For onedir builds only, specify the name of the directory in which all
supporting files (i.e. everything except the executable itself) will be
placed in. Use “.” to re-enable old onedir layout without contents
directory.

What To Bundle, Where To Search

—add-data SOURCE:DEST

Additional data files or directories containing data files to be added to
the application. The argument value should be in form of “source:dest_dir”,
where source is the path to file (or directory) to be collected, dest_dir
is the destination directory relative to the top-level application
directory, and both paths are separated by a colon (:). To put a file in
the top-level application directory, use . as a dest_dir. This option can
be used multiple times.

—add-binary SOURCE:DEST

Additional binary files to be added to the executable. See the
--add-data option for the format. This option can be used multiple
times.

-p, —paths DIR

A path to search for imports (like using PYTHONPATH).
Multiple paths are allowed, separated by ':', or
use this option multiple times. Equivalent to
supplying the pathex argument in the spec file.

—hidden-import, —hiddenimport MODULENAME

Name an import not visible in the code of the script(s). This option can be
used multiple times.

—collect-submodules MODULENAME

Collect all submodules from the specified package or module. This option
can be used multiple times.

—collect-data, —collect-datas MODULENAME

Collect all data from the specified package or module. This option can be
used multiple times.

—collect-binaries MODULENAME

Collect all binaries from the specified package or module. This option can
be used multiple times.

—collect-all MODULENAME

Collect all submodules, data files, and binaries from the specified package
or module. This option can be used multiple times.

—copy-metadata PACKAGENAME

Copy metadata for the specified package. This option can be used multiple
times.

—recursive-copy-metadata PACKAGENAME

Copy metadata for the specified package and all its dependencies. This
option can be used multiple times.

—additional-hooks-dir HOOKSPATH

An additional path to search for hooks. This option can be used multiple
times.

—runtime-hook RUNTIME_HOOKS

Path to a custom runtime hook file. A runtime 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 runtime environment. This option can be used
multiple times.

—exclude-module EXCLUDES

Optional module or package (the Python name, not the path name) that will
be ignored (as though it was not found). This option can be used multiple
times.

—splash IMAGE_FILE

(EXPERIMENTAL) Add an splash screen with the image
IMAGE_FILE to the application. The splash screen can
display progress updates while unpacking.

How To Generate

-d, —debug {all,imports,bootloader,noarchive}

Provide assistance with debugging a frozen application. This argument may
be provided multiple times to select several of the following options. —
all: All three of the following options. — imports: specify the -v option
to the underlying Python interpreter, causing it to print a message
each time a module is initialized, showing the place (filename or
built-in module) from which it is loaded. See
https://docs.python.org/3/using/cmdline.html#id4. — bootloader: tell the
bootloader to issue progress messages while initializing and starting the
bundled app. Used to diagnose problems with missing imports. —
noarchive: instead of storing all frozen Python source files as an
archive inside the resulting executable, store them as files in the
resulting output directory.

—optimize LEVEL

Bytecode optimization level used for collected python
modules and scripts. For details, see the section
“Bytecode Optimization Level” in PyInstaller manual.

—python-option PYTHON_OPTION

Specify a command-line option to pass to the Python interpreter at runtime.
Currently supports “v” (equivalent to “–debug imports”), “u”, “W <warning
control>”, “X <xoption>”, and “hash_seed=<value>”. For details, see the
section “Specifying Python Interpreter Options” in PyInstaller manual.

-s, —strip

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

—noupx

Do not use UPX even if it is available (works
differently between Windows 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 option can be used
multiple times.

Windows And Macos Specific Options

-c, —console, —nowindowed

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

-w, —windowed, —noconsole

Windows and macOS: do not provide a console window for standard i/o. On
macOS this also triggers building a macOS .app bundle. On Windows this
option is automatically set if the first script is a ‘.pyw’ file. This
option is ignored on *NIX systems.

—hide-console {hide-late,hide-early,minimize-late,minimize-early}

Windows only: in console-enabled executable, have bootloader automatically
hide or minimize the console window if the program owns the console window
(i.e., was not launched from an existing console window).

-i, —icon <FILE.ico or FILE.exe,ID or FILE.icns or Image or «NONE»>

FILE.ico: apply the 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
macOS. If an image file is entered that isn’t in the platform format (ico
on Windows, icns on Mac), PyInstaller tries to use Pillow to translate the
icon into the correct format (if Pillow is installed). Use “NONE” to not
apply any icon, thereby making the OS show some default (default: apply
PyInstaller’s icon). This option can be used multiple times.

—disable-windowed-traceback

Disable traceback dump of unhandled exception in windowed (noconsole) mode
(Windows and macOS only), and instead display a message that this feature
is disabled.

Windows Specific Options

—version-file FILE

Add a version resource from FILE to the exe.

—manifest <FILE or XML>

Add manifest FILE or XML to the exe.

-m <FILE or XML>

Deprecated shorthand for –manifest.

-r, —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
omitted or specified as wildcard *. This option can be used multiple
times.

—uac-admin

Using this option creates a Manifest that will request
elevation upon application start.

—uac-uiaccess

Using this option allows an elevated application to
work with Remote Desktop.

Macos Specific Options

—argv-emulation

Enable argv emulation for macOS app bundles. If
enabled, the initial open document/URL event is
processed by the bootloader and the passed file paths
or URLs are appended to sys.argv.

—osx-bundle-identifier BUNDLE_IDENTIFIER

macOS .app bundle identifier is used as the default unique program name for
code signing purposes. The usual form is a hierarchical name in reverse DNS
notation. For example: com.mycompany.department.appname (default: first
script’s basename)

—target-architecture, —target-arch ARCH

Target architecture (macOS only; valid values: x86_64, arm64, universal2).
Enables switching between universal2 and single-arch version of frozen
application (provided python installation supports the target
architecture). If not target architecture is not specified, the current
running architecture is targeted.

—codesign-identity IDENTITY

Code signing identity (macOS only). Use the provided identity to sign
collected binaries and generated executable. If signing identity is not
provided, ad- hoc signing is performed instead.

—osx-entitlements-file FILENAME

Entitlements file to use when code-signing the collected binaries (macOS
only).

Rarely Used Special Options

—runtime-tmpdir PATH

Where to extract libraries and support files in onefile mode. If this
option is given, the bootloader will ignore any temp-folder location
defined by the run-time OS. The _MEIxxxxxx-folder will be created here.
Please use this option only if you know what you are doing. Note that on
POSIX systems, PyInstaller’s bootloader does NOT perform shell-style
environment variable expansion on the given path string. Therefore, using
environment variables (e.g., ~ or $HOME) in path will NOT work.

—bootloader-ignore-signals

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

Excluding problematic files from UPX processing

Using UPX may end up corrupting a collected shared library. Known examples
of such corruption are Windows DLLs with Control Flow Guard (CFG) enabled, as well as Qt5 and Qt6
plugins. In such cases,
individual files may be need to be excluded from UPX processing, using
the --upx-exclude option (or using the upx_exclude argument
in the .spec file).

Changed in version 4.2: PyInstaller detects CFG-enabled DLLs and automatically excludes
them from UPX processing.

Changed in version 4.3: PyInstaller automatically excludes Qt5 and Qt6 plugins from
UPX processing.

Although PyInstaller attempts to automatically detect and exclude some of
the problematic files from UPX processing, there are cases where the
UPX excludes need to be specified manually. For example, 32-bit Windows
binaries from the PySide2 package (Qt5 DLLs and python extension modules)
have been reported
to be corrupted by UPX.

Changed in version 5.0: Unlike earlier releases that compared the provided UPX-exclude names
against basenames of the collect binary files (and, due to incomplete
case normalization, required provided exclude names to be lowercase
on Windows), the UPX-exclude pattern matching now uses OS-default
case sensitivity and supports the wildcard (*) operator. It also
supports specifying (full or partial) parent path of the file.

The provided UPX exclude patterns are matched against source (origin)
paths of the collected binary files, and the matching is performed from
right to left.

For example, to exclude Qt5 DLLs from the PySide2 package, use
--upx-exclude "Qt*.dll", and to exclude the python extensions
from the PySide2 package, use --upx-exclude "PySide2\*.pyd".

Supporting Multiple Python Environments

When you need to bundle your application 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 combinations of Python
and installed packages, and switch from one combination to another easily.
These are called virtual environments or venvs in short.

• Use venv to create as many different development environments as you need,
  each with its unique combination of Python and installed packages.

• Install PyInstaller in each virtual environment.

• Use PyInstaller to build your application 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 macOS, you switch environments at the command line.

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

Supporting Multiple Operating Systems

If you need to distribute your application for more than one OS,
for example both Windows and macOS, you must install PyInstaller
on each platform and bundle your app separately on each.

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

A File Sync & Share system like NextCloud is useful with virtual machines.
Install the synchronization client in each virtual machine,
all linked to your synchronization 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 multiple platforms, for
example GNU/Linux and macOS, you will need to set the PYINSTALLER_CONFIG_DIR
environment variable to different values on each platform otherwise
PyInstaller may cache files for one platform and use them on the other
platform, as by default it uses a subdirectory of your home directory
as its cache location.

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.

GNU/Linux

Windows

The developer needs to take
special care to include the Visual C++ run-time .dlls:
Python 3.5+ uses Visual Studio 2015 run-time, 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 options:

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

2. Include one of the VCRedist packages (the redistributable package files)
   into your application’s installer. This is Microsoft’s recommended way, see
   “Distributing Software that uses the Universal CRT“ in the above-mentioned
   link, numbers 2 and 3.

3. Install the Windows Software Development Kit (SDK) for Windows 10 and expand the
   .spec-file to include the required DLLs, see “Distributing Software that
   uses the Universal CRT“ in the above-mentioned link, number 6.

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

macOS

$ 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

$ /usr/local/bin/python3
Python 3.7.6 (v3.7.6:43364a7ae0, Dec 18 2019, 14:12:53)
[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.7.6 (v3.7.6:43364a7ae0, Dec 18 2019, 14:12:53)
[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

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>

Cygwin

Development Tools

For building the bootloader you’ll need a development environment.
You can run the following to install everything required:

• On Debian- or Ubuntu-like systems:

  sudo apt-get install build-essential zlib1g-dev
  

• On Fedora, RedHat and derivates:

  sudo yum groupinstall "Development Tools"
  sudo yum install zlib-devel
  

• For other Distributions please consult the distributions documentation.

Now you can build the bootloader as shown above.

Alternatively you may want to use the linux64 build-guest
provided by the Vagrantfile (see below).

Cross-Building for macOS

For cross-compiling for macOS you need the Clang/LLVM compiler, the
cctools (ld, lipo, …), and the macOS SDK. Clang/LLVM is a cross compiler by
default and is available on nearly every GNU/Linux distribution, so you just
need a proper port of the cctools and the macOS SDK.

This is easy to get and needs to be done only once and the result can be
transferred to you build-system. The build-system can then be a normal
(somewhat current) GNU/Linux system. [1]

export TARGET=OSX  # make the Vagrantfile build for macOS
vagrant up linux64 && vagrant halt linux64

mkdir -p ~/osxcross
tar -C ~/osxcross --xz -xf /vagrant/sdks/osx/osxcross.tar.xz
PATH=~/osxcross/bin/:$PATH
python ./waf all CC=x86_64-apple-darwin15-clang
python ./waf all CC=i386-apple-darwin15-clang

Build using Visual Studio C++

• With our wscript file, you don’t need to run vcvarsall.bat to ’switch’
  the environment between VC++ installations and target architecture. The
  actual version of C++ does not matter and the target architecture is
  selected by using the --target-arch= option.

• If you are not using Visual Studio for other work, installing only the
  standalone C++ build-tools might be the best option as it avoids bloating
  your system with stuff you don’t need (and saves a lot if installation
  time).

  Hint

  We recommend
  installing the build-tools software using the
  chocolatey package manager.
  While at a first glance it looks like overdose, this is the easiest
  way to install the C++ build-tools. It comes down to two lines in an
  administrative powershell:

  … one-line-install as written on the chocolatey homepage
  choco install -y python3 visualstudio2019-workload-vctools
  

• Useful Links:

  • Microsoft Visual C++ Build-Tools 2015

  • Microsoft Build-Tools for Visual Studio 2017.

After installing the C++ build-tool
you can build the bootloader as shown above.

Build using MinGW-w64

Please be aware of the restrictions mentioned above.

If Visual Studio is not convenient,
you can download and install the MinGW distribution from one of the
following locations:

• MinGW-w64 required, uses gcc 4.4 and up.

• TDM-GCC — MinGW (not used) and MinGW-w64 installers

Note: Please mind that using cygwin’s python or MinGW
when running ./waf will
create executables for cygwin, not for Windows.

On Windows, when using MinGW-w64, add PATH_TO_MINGWbin
to your system PATH. variable. Before building the
bootloader run for example:

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

Now you can build the bootloader as shown above.
If you have installed both Visual C++ and MinGW,
you might need to add run python ./waf --gcc all.

Build using cygwin and MinGW

Please be aware that
this will create executables for cygwin, not for ‘plain’ Windows.

Use cygwin’s setup.exe to install python and mingw.

Now you can build the bootloader as shown above.