Using PyInstaller¶
In the most simple case, set the current directory to the location of your program myscript.py and execute:
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-time.
For certain uses you may edit the contents of myscript.spec (described under Using Spec Files ). After you do this, you name the spec file to PyInstaller instead of the script:
The myscript.spec file contains most of the information provided by the options 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 options when running pyinstaller with the spec file. Only a few command-line options have an effect when building from a spec file.
You may give a path to the script or spec file, for example
pyinstaller "C:\Documents and Settings\project\myscript.spec"
Options¶
A full list of the pyinstaller command’s options are as follows:
Positional Arguments¶
Name of scriptfiles to be processed or exactly one .spec file. If a .spec file is specified, most options are unnecessary and are ignored.
Optional Arguments¶
show this help message and exit
Show program version info and exit.
Where to put the bundled app (default: ./dist)
Where to put all the temporary work files, .log, .pyz and etc. (default: ./build)
Replace output directory (default: SPECPATH/dist/SPECNAME) without asking for confirmation
Path to UPX utility (default: search the execution path)
Do not include unicode encoding support (default: included if available)
Clean PyInstaller cache and remove temporary files before building.
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¶
Create a one-folder bundle containing an executable (default)
Create a one-file bundled executable.
Folder to store the generated spec file (default: current directory)
-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¶
Additional non-binary files or folders to be added to the executable. The path separator is platform specific, os.pathsep (which is ; on Windows and : on most unix systems) is used. This option can be used multiple times.
—add-binary <SRC;DEST or SRC:DEST> ¶
Additional binary files to be added to the executable. See the —add-data option for more details. This option can be used multiple times.
-p DIR , —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 MODULENAME , —hiddenimport MODULENAME ¶
Name an import not visible in the code of the script(s). This option can be used multiple times.
Collect all submodules from the specified package or module. This option can be used multiple times.
—collect-data MODULENAME , —collect-datas MODULENAME ¶
Collect all data from the specified package or module. This option can be used multiple times.
Collect all binaries from the specified package or module. This option can be used multiple times.
Collect all submodules, data files, and binaries from the specified package or module. This option can be used multiple times.
Copy metadata for the specified package. This option can be used multiple times.
Copy metadata for the specified package and all its dependencies. This option can be used multiple times.
An additional path to search for hooks. This option can be used multiple times.
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.
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.
(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¶
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.
Specify a command-line option to pass to the Python interpreter at runtime. Currently supports “v” (equivalent to “–debug imports”), “u”, and “W <warning control>”.
Apply a symbol-table strip to the executable and shared libs (not recommended for Windows)
Do not use UPX even if it is available (works differently between Windows and *nix)
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 Mac Os X Specific Options¶
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 Mac OS X: do not provide a console window for standard i/o. On Mac OS this also triggers building a Mac OS .app bundle. On Windows this option is automatically set if the first script is a ‘.pyw’ file. This option is ignored on *NIX systems.
-i <FILE.ico or FILE.exe,ID or FILE.icns or Image or "NONE"> , —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 Mac OS. 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 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¶
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.
Generate an external .exe.manifest file instead of embedding the manifest into the exe. Applicable only to onedir mode; in onefile mode, the manifest is always embedded, regardless of this option.
-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 omitted or specified as wildcard *. This option can be used multiple times.
Using this option creates a Manifest that will request elevation upon application start.
Using this option allows an elevated application to work with Remote Desktop.
Windows Side-By-Side Assembly Searching Options (Advanced)¶
Any Shared Assemblies bundled into the application 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.
While searching for Shared or Private Assemblies to bundle into the application, 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 Specific Options¶
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.
Mac OS .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 ARCH , —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.
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.
Entitlements file to use when code-signing the collected binaries (macOS only).
Rarely Used Special Options¶
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.
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.
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 GNU/Linux:
Or in Windows, use the little-known BAT file line continuation:
Running PyInstaller from Python code¶
If you want to run PyInstaller from Python code, you can use the run function defined in PyInstaller.__main__ . For instance, the following code:
Is equivalent to:
Using UPX¶
UPX is a free utility for compressing executable files and libraries. It 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 file formats.
When UPX is available, PyInstaller uses it to individually compress each collected binary file (executable, shared library, or python extension) in order to reduce the overall size of the frozen application (the one-dir bundle directory, or the one-file executable). The frozen application’s executable itself is not UPX-compressed (regardless of one-dir or one-file mode), as most of its size comprises the embedded archive that already contains individually compressed files.
PyInstaller looks for the UPX in the standard executable path(s) (defined by PATH environment variable), or in the path specified via the —upx-dir command-line option. If found, it is used automatically. The use of UPX can be completely disabled using the —noupx command-line option.
UPX is currently used only on Windows. On other operating systems, the collected binaries are not processed even if UPX is found. The shared libraries (e.g., the Python shared library) built on modern linux distributions seem to break when processed with UPX, resulting in defunct application bundles. On macOS, UPX currently fails to process .dylib shared libraries; furthermore the UPX-compressed files fail the validation check of the codesign utility, and therefore cannot be code-signed (which is a requirement on the Apple M1 platform).
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" .
Splash Screen (Experimental)¶
This feature is incompatible with macOS. In the current design, the splash screen operates in a secondary thread, which is disallowed by the Tcl/Tk (or rather, the underlying GUI toolkit) on macOS.
Some applications may require a splash screen as soon as the application (bootloader) has been started, because especially in onefile mode large applications may have long extraction/startup times, while the bootloader prepares everything, where the user cannot judge whether the application was started successfully or not.
The bootloader is able to display a one-image (i.e. only an image) splash screen, which is displayed before the actual main extraction process starts. The splash screen supports non-transparent and hard-cut-transparent images as background image, so non-rectangular splash screens can also be displayed.
This splash screen is based on Tcl/Tk, which is the same library used by the Python module tkinter. PyInstaller bundles the dynamic libraries of tcl and tk into the application at compile time. These are loaded into the bootloader at startup of the application after they have been extracted (if the program has been packaged as an onefile archive). Since the file sizes of the necessary dynamic libraries are very small, there is almost no delay between the start of the application and the splash screen. The compressed size of the files necessary for the splash screen is about 1.5 MB.
As an additional feature, text can optionally be displayed on the splash screen. This can be changed/updated from within Python. This offers the possibility to display the splash screen during longer startup procedures of a Python program (e.g. waiting for a network response or loading large files into memory). You can also start a GUI behind the splash screen, and only after it is completely initialized the splash screen can be closed. Optionally, the font, color and size of the text can be set. However, the font must be installed on the user system, as it is not bundled. If the font is not available, a fallback font is used.
If the splash screen is configured to show text, it will automatically (as onefile archive) display the name of the file that is currently being unpacked, this acts as a progress bar.
The pyi_splash Module¶
The splash screen is controlled from within Python by the pyi_splash module, which can be imported at runtime. This module cannot be installed by a package manager because it is part of PyInstaller and is included as needed. This module must be imported within the Python program. The usage is as follows:
Of course the import should be in a try . except block, in case the program is used externally as a normal Python script, without a bootloader. For a detailed description see pyi_splash Module (Detailed) .
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 location of the temporary directory at compile time. This can be done using the —runtime-tmpdir option. If this option is given, the bootloader will ignore any temp-folder location defined by the run-time OS. Please use this option only if you know what you are doing.
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.
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:
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:
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.
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:
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:
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 pyi-set_version command:
pyi-set_version version_text_file executable_file
The pyi-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 macOS App Bundles¶
Under macOS, PyInstaller always builds a UNIX executable in dist . If you specify —onedir , the output is a folder named myscript containing supporting 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 option, the dist folder also contains a macOS 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 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 supporting files, just as in the —onedir folder.
Use the —icon argument to specify a custom icon for the application. 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 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).
You can add other items to the Info.plist by editing the spec file; see Spec File Options for a macOS 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 compatible to newer releases, but it is not backward compatible 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 runtime dynamic link error) if it is executed on an older version of GNU/Linux.
The solution is to always build your app on the oldest version of GNU/Linux you mean to support. It should continue 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 compatible. As a result you cannot bundle your app on a 32-bit system and run it on a 64-bit installation, nor vice-versa. You must make a unique version of the app for each word-length supported.
Note that PyInstaller does bundle other shared libraries that are discovered via dependency analysis, such as libstdc++.so.6, libfontconfig.so.1, libfreetype.so.6. These libraries may be required on systems where older (and thus incompatible) versions of these libraries are available. On the other hand, the bundled libraries may cause issues when trying to load a system-provided shared library that is linked against a newer version of the system-provided library.
For example, system-installed mesa DRI drivers (e.g., radeonsi_dri.so) depend on the system-provided version of libstdc++.so.6. If the frozen application bundles an older version of libstdc++.so.6 (as collected from the build system), this will likely cause missing symbol errors and prevent the DRI drivers from loading. In this case, the bundled libstdc++.so.6 should be removed. However, this may not work on a different distribution that provides libstdc++.so.6 older than the one from the build system; in that case, the bundled version should be kept, because the system-provided version may lack the symbols required by other collected binaries that depend on libstdc++.so.6.
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:
Build on Windows 7 which has been reported to work.
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.
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¶
Making macOS apps Forward-Compatible¶
On macOS, system components from one version of the OS are usually compatible with later versions, but they may not work with earlier versions. While PyInstaller does not collect system components of the OS, the collected 3rd party binaries (e.g., python extension modules) are built against specific version of the OS libraries, and may or may not support older OS versions.
As such, the only way to ensure that your frozen application supports an older version of the OS is to freeze it on the oldest version of the OS that you wish to support. This applies especially when building with Homebrew python, as its binaries usually explicitly target the running OS.
For example, to ensure compatibility with “Mojave” (10.14) and later versions, you should set up a full environment (i.e., install python, PyInstaller, your application’s code, and all its dependencies) in a copy of macOS 10.14, using a virtual machine if necessary. Then use PyInstaller to freeze your application in that environment; the generated frozen application should be compatible with that and later versions of macOS.
Building 32-bit Apps in macOS¶
This section is largely obsolete, as support for 32-bit application was removed in macOS 10.15 Catalina (for 64-bit multi-arch support on modern versions of macOS, see here ). However, PyInstaller still supports building 32-bit bootloader, and 32-bit/64-bit Python installers are still available from python.org for (some) versions of Python 3.7.
Older versions of macOS 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, resulting in a 64-bit executable. To create a 32-bit executable, run PyInstaller under a 32-bit Python.
To verify that the installed python version supports execution in either 64- or 32-bit mode, use the file command on the Python executable:
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:
PyInstaller does not provide pre-built 32-bit bootloaders for macOS anymore. In order to use PyInstaller with 32-bit python, you need to build the bootloader yourself, using an XCode version that still supports compiling 32-bit. Depending on the compiler/toolchain, you may also need to explicitly pass —target-arch=32bit to the waf command.
Getting the Opened Document Names¶
When user double-clicks a document of a type that is registered with your application, or when a user drags a document and drops it on your application’s icon, macOS launches your application and provides the name(s) of the opened document(s) in the form of an OpenDocument AppleEvent.
These events are typically handled via installed event handlers in your application (e.g., using Carbon API via ctypes , or using facilities provided by UI toolkits, such as tkinter or PyQt5 ).
Alternatively, PyInstaller also supports conversion of open document/URL events into arguments that are appended to sys.argv . This applies only to events received during application launch, i.e., before your frozen code is started. To handle events that are dispatched while your application is already running, you need to set up corresponding event handlers.
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:
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:
When working with a 64-bit Python executable proceed as follows:
© Copyright This document has been placed in the public domain.. Revision 4222dc4d .
Introduction
I have a use case where I want to convert my Python script to standalone executable so that I do not need to type python before it to run the script. On Linux, it is easy to achieve with the help of shebang. However, on Windows, it does not work. Then I thought I might convert the script to Windows executable.
We can use pyinstaller to convert python script to Windows executable files. You can install it with pip:
How to use pyinstaller
The most simple way to run pyinstaller is to invoke it without options:
It will create a dist/my_script directory where the generated executable resides with other DLL files. This executable file can not run alone: it must rely on other DLL files.
To create a standalone executable, we can use —onefile option.
To build an executable which runs on command line and does not need a GUI windows, we can use the —console option.
We can then generate the executable with the following command:
The generated executable will be dist/my_script.exe .
Reduce the size of executable
One problem is that the generated executable file is huge even if the script only contains a few lines of code.
Create a virtual environment
According to post here, to reduce the size of the produced executable, we can create a clean virtual environment where only packages required for our script are installed.
In my case, after building the executable inside a virtual env, I have reduced the executable size from more than 200Mb to only 6Mb!
Using UPX
An additional way to reduce executable size is to use UPX to compress files. You can download the UPX windows release file and extract it to a folder. When running the pyinstaller, you can use —upx-dir to include UPX support:
In the above command, you only need to specify the path of the directory containing upx.exe .
However, certain DLL files which is need by the executable should not be compressed by UPX. If they are compressed, you may encounter errors when you run the produced executable:
Those DLLs failing to load should not be compressed by UPX. You can add —upx-exclude option to pyinstaller when building the executable, and this options can be used multiple times to exclude several files. For example:
Создаём установщик веб-приложения Python, включающий Apache, Django и PostgreSQL для ОС Windows
Данный пост является продолжением первой части статьи на Хабре, где было подробно рассказано о развертывании Django стека на MS Windows. Далее будет представлена пошаговая инструкция по созданию инсталлятора, который будет автоматизировать процесс установки стека на других компьютерах без необходимости работы в командной строке, созданием виртуальных машин и т.д., где вся последовательность действий будет сводится к действиям Далее -> Далее -> Готово.
Итак, что должен делать инсталлятор:
- Распаковать все необходимые программы и компоненты в указанную пользователем директорию.
- Выполнить проверки перед установкой.
- Прописать интерпретатор Python в реестре Windows.
- Установить, если ещё не установлены, программные библиотеки зависимостей.
- Создать службы Apache и PostgreSQL, затем стартовать их.
- Дополнительным плюсом будет автоматическое создание программы деинсталлятора, который удалит установленный стек, если пользователь этого захочет.
Лучше всего то, что для создания базового установщика вообще не требуется никаких сценариев, поскольку Inno Setup поставляется с графическим мастером, который на удивление хорошо справляется с базовыми установщиками.
Логика установки может быть написана на ЯП Pascal, а не на запутанных пользовательских действиях в Wix. Единственным недостатком его является то, что он создает только exe, формат файлов msi не поддерживается.
Шаг 1. Установка Inno Setup
Дополнительные комментарии здесь не нужны, т.к. скачивание и установка программы инсталлятора тривиальна.
Шаг 2: Создание сценария установки Inno Setup
Создадим заготовку сценария установки Inno Setup (файл *.iss) с помощью Мастера сценариев установки.
; Script generated by the Inno Setup Script Wizard.
; SEE THE DOCUMENTATION FOR DETAILS ON CREATING INNO SETUP SCRIPT FILES!
#define MyAppName «Severcart»
#define MyAppVersion «1.21.0»
#define MyAppPublisher «Severcart Inc.»
#define MyAppURL «https://www.severcart.ru/»
[Setup]
; NOTE: The value of AppId uniquely identifies this application. Do not use the same AppId value in installers for other applications.
; (To generate a new GUID, click Tools | Generate GUID inside the IDE.)
AppId=<<4FAF87DC-4DBD-42CE-A2A2-B6D559E76BDC>
AppName=<#MyAppName>
AppVersion=<#MyAppVersion>
;AppVerName= <#MyAppName><#MyAppVersion>
AppPublisher=<#MyAppPublisher>
AppPublisherURL=<#MyAppURL>
AppSupportURL=<#MyAppURL>
AppUpdatesURL=<#MyAppURL>
DefaultDirName=c:\severcart
DefaultGroupName=<#MyAppName>
; Uncomment the following line to run in non administrative install mode (install for current user only.)
;PrivilegesRequired=lowest
OutputDir=C:\Users\Developer\Desktop\Output
OutputBaseFilename=mysetup
Compression=lzma
SolidCompression=yes
WizardStyle=modern
[Languages]
Name: «russian»; MessagesFile: «compiler:Languages\Russian.isl»
[Files]
Source: «C:\severcart\*»; DestDir: «
; NOTE: Don’t use «Flags: ignoreversion» on any shared system files
Шаг 3. Проверки перед установкой
Перед распаковкой программ в каталог и изменения в реестре необходимо проверить, что TCP порты свободны для работы Apache и PostgreSQL, также нужно проверить минимальные системные требования ОС Windows, т.к. как уже оговаривалось в Первой части данной статьи устанавливаемая версия Python будет работать только начиная с версии MS Windows 8 (версия ядра 6.2).
Для выполнения необходимых проверок воспользуемся секцией [Code] установочного файла. Раздел [Code] – это необязательный раздел, определяющий сценарий Pascal. Сценарий Pascal можно использовать для настройки установки или удаления разными способами. Обратите внимание, что создать сценарий Pascal непросто и требует опыта работы с Inno Setup и умений программирования на Pascal или, по крайней мере, на аналогичном языке программирования.
function IsWindowsVersionOrNewer(Major, Minor: Integer): Boolean;
var
Version: TWindowsVersion;
begin
GetWindowsVersionEx(Version);
Result := (Version.Major > Major) or ((Version.Major = Major) and (Version.Minor >= Minor));
end;
function IsWindows8OrNewer: Boolean;
begin
Result := IsWindowsVersionOrNewer(6, 2);
end;
Для проверки доступности TCP портов создадим следующую функцию:
function CheckPortOccupied(Port:String):Boolean;
var
ResultCode: Integer;
begin
Exec(ExpandConstant(‘
if ResultCode <> 1 then
begin
Log(‘this port(‘+Port+’) is occupied’);
Result := True;
end else
begin
Result := False;
end;
end;
Вызывать проверочные функции будем в функции InitializeSetup, вызываемой во время инициализации установки. Возвращает False, для отмены установки, в противном случае — True.
function InitializeSetup(): Boolean;
var
port_80_check, port_5432_check: boolean;
begin
if not IsWindows8OrNewer() then begin
MsgBox(‘Установка невозможна. Программа работает начиная с Windows 2012 и Windows 8.0.’,mbError,MB_OK);
Abort();
Result := False;
end;
port_80_check := CheckPortOccupied(‘8080’);
if port_80_check then begin
MsgBox(‘Установка невозможна. TCP порт 8080 занят.’,mbError,MB_OK);
Abort();
Result := False;
end;
port_5432_check := CheckPortOccupied(‘5432’);
if port_5432_check then begin
MsgBox(‘Установка невозможна. TCP порт 5432 занят.’,mbError,MB_OK);
Result := False;
Abort();
end;
Result := True;
Шаг 4. Прописываем Python в реестре Windows
В этом необязательном разделе определяются любые ключи / значения реестра, которые программа установки должна создать или изменить в системе пользователя.
Для этого добавляем ключи PYTHONPATH, PYTHONHOME и обновляем переменную Path.
sys.path содержит список строк, предоставляющих места поиска модулей и пакетов будущего Python проекта. Он инициализируется из переменной среды PYTHONPATH и другими настройками.
PYTHONHOME — домашний каталог Python.
PATH — это переменная окружения, которая ОС использует для поиска исполняемых файлов в командной строке или окне терминала.
Root: HKLM; Subkey: «SYSTEM\CurrentControlSet\Control\Session Manager\Environment»; \
ValueType: expandsz; ValueName: «Path»; ValueData: «
Root: HKLM; Subkey: «SYSTEM\CurrentControlSet\Control\Session Manager\Environment»; \
ValueType: expandsz; ValueName: «PYTHONPATH»; ValueData: «
Root: HKLM; Subkey: «SYSTEM\CurrentControlSet\Control\Session Manager\Environment»; \
ValueType: expandsz; ValueName: «PYTHONHOME»; ValueData: «
Шаг 5. Создаем конфигурационные файлы служб Apache и PostgreSQL
Для создания конфигурационных файлов воспользуемся 2я Python скриптами, которые сгенерируют конфигурационные на основе заданного пользователем пути установки.
Вызов скриптов будет производиться в разделе [Run] установщика.
Раздел [Run] является необязательным и указывает любое количество программ, которые необходимо выполнить после успешной установки программы, но до того, как программа установки отобразит последнее диалоговое окно.
Далее в эту же секцию добавим скрытую установку распространяемые пакеты Visual Studio без которых службы Apache и PostgreSQL работать не будут.
Filename: «
Filename: «
Filename: «
Filename: «
Filename: «
Filename: «
Содержимое файла create_http_conf.py
Содержимое файла install.bat
..\Apache24\bin\httpd.exe -k install -n «Apache» > install.log 2>&1
..\postgresql\bin\pg_ctl.exe register -N «PostgreSQL» -D ..\postgresql\data > install.log 2>&1
Содержимое файла services_start.bat
net start «Apache»
net start «PostgreSQL»
Шаг 6: Создаем деинсталлятор
Для любого инсталлятора также необходимо предусмотреть возможность создания программы деинсталлятора. К счастью программа Inno Setup сделает эту работу за нас, за исключением некоторых действий, которые нужно предусмотреть для очистки следов присутствия программы в ОС.
Для этого в секции [UninstallRun] пропишем выполнение bat скрипта Windows для остановки установленных служб, а также их удаления.
[UninstallRun]
Filename: «
Содержимое bat скрипта:
SC STOP Apache
SC STOP PostgreSQL
SC DELETE Apache
SC DELETE PostgreSQL
Скрипт выполняет остановку служб, затем удаляет службы Apache и PostgreSQL из перечня системных служб Windows.
Шаг 7. Подписание исполняемого файла инсталлятора ЭП разработчика
Сертификаты подписи кода используются разработчиками программного обеспечения для цифровой подписи приложений и программ, чтобы доказать, что файл, загружаемый пользователем, является подлинным и не был взломан. Это особенно важно для издателей, которые распространяют свое программное обеспечение через сторонние сайты загрузки, которые они не могут контролировать. Основные операционные системы будут показывать конечным пользователям сообщение об ошибке, если программное обеспечение, которое они пытаются установить, не подписано доверенным центром сертификации.
Купить сертификат разработчика PFX, например можно здесь. Сертификат приобретается на год.
Предпоследним шагом над работы с инсталлятором будет автоматический запуск программы signtool.exe для подписания готового инсталлятора в формате exe после того как программа Inno Setup завершит свою работу. SignTool — это программа командной строки, которая подписывает файлы цифровой подписью, проверяет подписи в файлах и временные метки файлов. По умолчанию в комплекте поставки Windows программа signtool.exe отсутствует, поэтому скачиваем и устанавливаем Windows 10 SDK.
По окончании установки вы найдете signtool.exe в каталогах:
- x86 -> c:\Program Files (x86)\Windows Kits\10\bin\x86\
- x64 -> c:\Program Files (x86)\Windows Kits\10\bin\x64\
Далее настроим автоматическое подписание файла. Выбираем «Configure Sign Tools. » из меню «Tools».
Далее нажимаем на кнопку «Add»
Дадим инструменту имя. Это имя, которое вы будете использовать при обращении к инструменту в сценариях установщика. Я назвал свой signtool, потому что использую signtool.exe.
Вставьте текст, который вы используете для подписи исполняемых файлов из командной строки. Замените имя подписываемого файла на $f. Inno Setup заменит переменную $f подписываемым файлом.
«C:\Program Files (x86)\Windows Kits\10\bin\x86\signtool.exe» sign /f «C:\MY_CODE_SIGNING.PFX» /t timestamp.comodoca.com/authenticode /p MY_PASSWORD $f
После нажатия OK вы закончите настройку инструмента подписи.
Добавим следующий сценарий в раздел [Setup], чтобы использовать только что настроенный инструмент подписи. Это предполагает, что вы назвали свой инструмент signtool.
Шаг 8. Собираем инсталлятор
#define MyAppName «Severcart»
#define MyAppVersion «1.21.0»
#define MyAppPublisher «Severcart Inc.»
#define MyAppURL «www.severcart.ru»
[Setup]
; NOTE: The value of AppId uniquely identifies this application.
; Do not use the same AppId value in installers for other applications.
; (To generate a new GUID, click Tools | Generate GUID inside the IDE.)
SignTool=signtool
AppId=<<2CF113D5-B49D-47EF-B85F-AE06EB0E78EB>>
AppName=<#MyAppName>
AppVersion=<#MyAppVersion>
;AppVerName= <#MyAppName><#MyAppVersion>
AppPublisher=<#MyAppPublisher>
AppPublisherURL=<#MyAppURL>
AppSupportURL=<#MyAppURL>
AppUpdatesURL=<#MyAppURL>
DefaultDirName=c:\severcart
DefaultGroupName=<#MyAppName>
OutputBaseFilename=setup
Compression=lzma
SolidCompression=yes
ChangesEnvironment=yes
; Uninstall options
Uninstallable=yes
CreateUninstallRegKey=yes
;WizardSmallImageFile=logo3.bmp
[Languages]
Name: «russian»; MessagesFile: «compiler:Languages\Russian.isl»
[Files]
Source: «C:\severcart\*»; Excludes: «*.pyc»; DestDir: «
[Registry]
Root: HKLM; Subkey: «SYSTEM\CurrentControlSet\Control\Session Manager\Environment»; \
ValueType: expandsz; ValueName: «Path»; ValueData: «
Root: HKLM; Subkey: «SYSTEM\CurrentControlSet\Control\Session Manager\Environment»; \
ValueType: expandsz; ValueName: «PYTHONPATH»; ValueData: «
Root: HKLM; Subkey: «SYSTEM\CurrentControlSet\Control\Session Manager\Environment»; \
ValueType: expandsz; ValueName: «PYTHONHOME»; ValueData: «
[Run]
Filename: «
Filename: «
Filename: «
Filename: «
Filename: «
Filename: «
[UninstallRun]
Filename: «
[Code]
function IsWindowsVersionOrNewer(Major, Minor: Integer): Boolean;
var
Version: TWindowsVersion;
begin
GetWindowsVersionEx(Version);
Result :=
(Version.Major > Major) or
((Version.Major = Major) and (Version.Minor >= Minor));
end;
function IsWindows8OrNewer: Boolean;
begin
Result := IsWindowsVersionOrNewer(6, 2);
end;
function CheckPortOccupied(Port:String):Boolean;
var
ResultCode: Integer;
begin
Exec(ExpandConstant(‘
if ResultCode <> 1 then
begin
Log(‘this port(‘+Port+’) is occupied’);
Result := True;
end else
begin
Result := False;
end;
end;
function InitializeSetup(): Boolean;
var
port_80_check, port_5432_check: boolean;
begin
if not IsWindows8OrNewer() then begin
MsgBox(‘Установка невозможна. Программа работает начиная с Windows 2012 и Windows 8.0.’,mbError,MB_OK);
Abort();
Result := False;
end;
port_80_check := CheckPortOccupied(‘8080’);
if port_80_check then begin
MsgBox(‘Установка невозможна. TCP порт 8080 занят.’,mbError,MB_OK);
Abort();
Result := False;
end;
port_5432_check := CheckPortOccupied(‘5432’);
if port_5432_check then begin
MsgBox(‘Установка невозможна. TCP порт 5432 занят.’,mbError,MB_OK);
Result := False;
Abort();
end;
Result := True;
Using PyInstaller to Easily Distribute Python Applications
Are you jealous of Go developers building an executable and easily shipping it to users? Wouldn’t it be great if your users could run your application without installing anything? That is the dream, and PyInstaller is one way to get there in the Python ecosystem.
There are countless tutorials on how to set up virtual environments, manage dependencies, avoid dependency pitfalls, and publish to PyPI, which is useful when you’re creating Python libraries. There is much less information for developers building Python applications. This tutorial is for developers who want to distribute applications to users who may or may not be Python developers.
In this tutorial, you’ll learn the following:
- How PyInstaller can simplify application distribution
- How to use PyInstaller on your own projects
- How to debug PyInstaller errors
- What PyInstaller can’t do
PyInstaller gives you the ability to create a folder or executable that users can immediately run without any extra installation. To fully appreciate PyInstaller’s power, it’s useful to revisit some of the distribution problems PyInstaller helps you avoid.
Free Bonus: 5 Thoughts On Python Mastery, a free course for Python developers that shows you the roadmap and the mindset you’ll need to take your Python skills to the next level.
Distribution Problems
Setting up a Python project can be frustrating, especially for non-developers. Often, the setup starts with opening a Terminal, which is a non-starter for a huge group of potential users. This roadblock stops users even before the installation guide delves into the complicated details of virtual environments, Python versions, and the myriad of potential dependencies.
Think about what you typically go through when setting up a new machine for Python development. It probably goes something like this:
- Download and install a specific version of Python
- Set up pip
- Set up a virtual environment
- Get a copy of your code
- Install dependencies
Stop for a moment and consider if any of the above steps make any sense if you’re not a developer, let alone a Python developer. Probably not.
These problems explode if your user is lucky enough to get to the dependencies portion of the installation. This has gotten much better in the last few years with the prevalence of wheels, but some dependencies still require C/C++ or even FORTRAN compilers!
This barrier to entry is way too high if your goal is to make an application available to as many users as possible. As Raymond Hettinger often says in his excellent talks, “There has to be a better way.”
PyInstaller
PyInstaller abstracts these details from the user by finding all your dependencies and bundling them together. Your users won’t even know they’re running a Python project because the Python Interpreter itself is bundled into your application. Goodbye complicated installation instructions!
PyInstaller performs this amazing feat by introspecting your Python code, detecting your dependencies, and then packaging them into a suitable format depending on your Operating System.
There are lots of interesting details about PyInstaller, but for now you’ll learn the basics of how it works and how to use it. You can always refer to the excellent PyInstaller docs if you want more details.
In addition, PyInstaller can create executables for Windows, Linux, or macOS. This means Windows users will get a .exe , Linux users get a regular executable, and macOS users get a .app bundle. There are some caveats to this. See the limitations section for more information.
Preparing Your Project
PyInstaller requires your application to conform to some minimal structure, namely that you have a CLI script to start your application. Often, this means creating a small script outside of your Python package that simply imports your package and runs main() .
The entry-point script is a Python script. You can technically do anything you want in the entry-point script, but you should avoid using explicit relative imports. You can still use relative imports throughout the rest your application if that’s your preferred style.
Note: An entry-point is the code that starts your project or application.
You can give this a try with your own project or follow along with the Real Python feed reader project. For more detailed information on the reader project, check out the the tutorial on Publishing a Package on PyPI.
The first step to building an executable version of this project is to add the entry-point script. Luckily, the feed reader project is well structured, so all you need is a short script outside the package to run it. For example, you can create a file called cli.py alongside the reader package with the following code:
This cli.py script calls main() to start up the feed reader.
Creating this entry-point script is straightforward when you’re working on your own project because you’re familiar with the code. However, it’s not as easy to find the entry-point of another person’s code. In this case, you can start by looking at the setup.py file in the third-party project.
Look for a reference to the entry_points argument in the project’s setup.py . For example, here’s the reader project’s setup.py :
As you can see, the entry-point cli.py script calls the same function mentioned in the entry_points argument.
After this change, the reader project directory should look like this, assuming you checked it out into a folder called reader :
Notice there is no change to the reader code itself, just a new file called cli.py . This entry-point script is usually all that’s necessary to use your project with PyInstaller.
However, you’ll also want to look out for uses of __import__() or imports inside of functions. These are referred to as hidden imports in PyInstaller terminology.
You can manually specify the hidden imports to force PyInstaller to include those dependencies if changing the imports in your application is too difficult. You’ll see how to do this later in this tutorial.
Once you can launch your application with a Python script outside of your package, you’re ready to give PyInstaller a try at creating an executable.
Using PyInstaller
The first step is to install PyInstaller from PyPI. You can do this using pip like other Python packages:
pip will install PyInstaller’s dependencies along with a new command: pyinstaller . PyInstaller can be imported in your Python code and used as a library, but you’ll likely only use it as a CLI tool.
You’ll use the library interface if you create your own hook files.
You’ll increase the likelihood of PyInstaller’s defaults creating an executable if you only have pure Python dependencies. However, don’t stress too much if you have more complicated dependencies with C/C++ extensions.
PyInstaller supports lots of popular packages like NumPy, PyQt, and Matplotlib without any additional work from you. You can see more about the list of packages that PyInstaller officially supports by referring to the PyInstaller documentation.
Don’t worry if some of your dependencies aren’t listed in the official docs. Many Python packages work fine. In fact, PyInstaller is popular enough that many projects have explanations on how to get things working with PyInstaller.
In short, the chances of your project working out of the box are high.
To try creating an executable with all the defaults, simply give PyInstaller the name of your main entry-point script.
First, cd in the folder with your entry-point and pass it as an argument to the pyinstaller command that was added to your PATH when PyInstaller was installed.
For example, type the following after you cd into the top-level reader directory if you’re following along with the feed reader project:
Don’t be alarmed if you see a lot of output while building your executable. PyInstaller is verbose by default, and the verbosity can be cranked way up for debugging, which you’ll see later.
Digging Into PyInstaller Artifacts
PyInstaller is complicated under the hood and will create a lot of output. So, it’s important to know what to focus on first. Namely, the executable you can distribute to your users and potential debugging information. By default, the pyinstaller command will create a few things of interest:
- A *.spec file
- A build/ folder
- A dist/ folder
Spec File
The spec file will be named after your CLI script by default. Sticking with our previous example, you’ll see a file called cli.spec . Here’s what the default spec file looks like after running PyInstaller on the cli.py file:
This file will be automatically created by the pyinstaller command. Your version will have different paths, but the majority should be the same.
Don’t worry, you don’t need to understand the above code to effectively use PyInstaller!
This file can be modified and re-used to create executables later. You can make future builds a bit faster by providing this spec file instead of the entry-point script to the pyinstaller command.
There are a few specific use-cases for PyInstaller spec files. However, for simple projects, you won’t need to worry about those details unless you want to heavily customize how your project is built.
Build Folder
The build/ folder is where PyInstaller puts most of the metadata and internal bookkeeping for building your executable. The default contents will look something like this:
The build folder can be useful for debugging, but unless you have problems, this folder can largely be ignored. You’ll learn more about debugging later in this tutorial.
Dist Folder
After building, you’ll end up with a dist/ folder similar to the following:
The dist/ folder contains the final artifact you’ll want to ship to your users. Inside the dist/ folder, there is a folder named after your entry-point. So in this example, you’ll have a dist/cli folder that contains all the dependencies and executable for our application. The executable to run is dist/cli/cli or dist/cli/cli.exe if you’re on Windows.
You’ll also find lots of files with the extension .so , .pyd , and .dll depending on your Operating System. These are the shared libraries that represent the dependencies of your project that PyInstaller created and collected.
Note: You can add *.spec , build/ , and dist/ to your .gitignore file to keep git status clean if you’re using git for version control. The default GitHub gitignore file for Python projects already does this for you.
You’ll want to distribute the entire dist/cli folder, but you can rename cli to anything that suits you.
At this point you can try running the dist/cli/cli executable if you’re following along with the feed reader example.
You’ll notice that running the executable results in errors mentioning the version.txt file. This is because the feed reader and its dependencies require some extra data files that PyInstaller doesn’t know about. To fix that, you’ll have to tell PyInstaller that version.txt is required, which you’ll learn about when testing your new executable.
Customizing Your Builds
PyInstaller comes with lots of options that can be provided as spec files or normal CLI options. Below, you’ll find some of the most common and useful options.
Change the name of your executable.
This is a way to avoid your executable, spec file, and build artifact folders being named after your entry-point script. —name is useful if you have a habit of naming your entry-point script something like cli.py , as I do.
You can build an executable called realpython from the cli.py script with a command like this:
Package your entire application into a single executable file.
The default options create a folder of dependencies and and executable, whereas —onefile keeps distribution easier by creating only an executable.
This option takes no arguments. To bundle your project into a single file, you can build with a command like this:
With the above command, your dist/ folder will only contain a single executable instead of a folder with all the dependencies in separate files.
List multiple top-level imports that PyInstaller was unable to detect automatically.
This is one way to work around your code using import inside functions and __import__() . You can also use —hidden-import multiple times in the same command.
This option requires the name of the package that you want to include in your executable. For example, if your project imported the requests library inside of a function, then PyInstaller would not automatically include requests in your executable. You could use the following command to force requests to be included:
You can specify this multiple times in your build command, once for each hidden import.
—add-data and —add-binary
Instruct PyInstaller to insert additional data or binary files into your build.
This is useful when you want to bundle in configuration files, examples, or other non-code data. You’ll see an example of this later if you’re following along with the feed reader project.
Exclude some modules from being included with your executable
This is useful to exclude developer-only requirements like testing frameworks. This is a great way to keep the artifact you give users as small as possible. For example, if you use pytest, you may want to exclude this from your executable:
Avoid automatically opening a console window for stdout logging.
This is only useful if you’re building a GUI-enabled application. This helps your hide the details of your implementation by allowing users to never see a terminal.
Similar to the —onefile option, -w takes no arguments:
As mentioned earlier, you can reuse the automatically generated .spec file to further customize your executable. The .spec file is a regular Python script that implicitly uses the PyInstaller library API.
Since it’s a regular Python script, you can do almost anything inside of it. You can refer to the official PyInstaller Spec file documentation for more information on that API.
Testing Your New Executable
The best way to test your new executable is on a new machine. The new machine should have the same OS as your build machine. Ideally, this machine should be as similar as possible to what your users use. That may not always be possible, so the next best thing is testing on your own machine.
The key is to run the resulting executable without your development environment activated. This means run without virtualenv , conda , or any other environment that can access your Python installation. Remember, one of the main goals of a PyInstaller-created executable is for users to not need anything installed on their machine.
Picking up with the feed reader example, you’ll notice that running the default cli executable in the dist/cli folder fails. Luckily the error points you to the problem:
The importlib_resources package requires a version.txt file. You can add this file to the build using the —add-data option. Here’s an example of how to include the required version.txt file:
This command tells PyInstaller to include the version.txt file in the importlib_resources folder in a new folder in your build called importlib_resources .
Note: The pyinstaller commands use the \ character to make the command easier to read. You can omit the \ when running commands on your own or copy and paste the commands as-is below provided you’re using the same paths.
You’ll want to adjust the path in the above command to match where you installed the feed reader dependencies.
Now running the new executable will result in a new error about a config.cfg file.
This file is required by the feed reader project, so you’ll need to make sure to include it in your build:
Again, you’ll need to adjust the path to the file based on where you have the feed reader project.
At this point, you should have a working executable that can be given directly to users!
Debugging PyInstaller Executables
As you saw above, you might encounter problems when running your executable. Depending on the complexity of your project, the fixes could be as simple as including data files like the feed reader example. However, sometimes you need more debugging techniques.
Below are a few common strategies that are in no particular order. Often times one of these strategies or a combination will lead to a break-through in tough debugging sessions.
Use the Terminal
First, try running the executable from a terminal so you can see all the output.
Remember to remove the -w build flag to see all the stdout in a console window. Often, you’ll see ImportError exceptions if a dependency is missing.
Debug Files
Inspect the build/cli/warn-cli.txt file for any problems. PyInstaller creates lots of output to help you understand exactly what it’s creating. Digging around in the build/ folder is a great place to start.
Single Directory Builds
Use the —onedir distribution mode of creating distribution folder instead of a single executable. Again, this is the default mode. Building with —onedir gives you the opportunity to inspect all the dependencies included instead of everything being hidden in a single executable.
—onedir is useful for debugging, but —onefile is typically easier for users to comprehend. After debugging you may want to switch to —onefile mode to simplify distribution.
Additional CLI Options
PyInstaller also has options to control the amount of information printed during the build process. Rebuild the executable with the —log-level=DEBUG option to PyInstaller and review the output.
PyInstaller will create a lot of output when increasing the verbosity with —log-level=DEBUG . It’s useful to save this output to a file you can refer to later instead of scrolling in your Terminal. To do this, you can use your shell’s redirection functionality. Here’s an example:
By using the above command, you’ll have a file called build.txt containing lots of additional DEBUG messages.
Note: The standard redirection with > is not sufficient. PyInstaller prints to the stderr stream, not stdout . This means you need to redirect the stderr stream to a file, which can be done using a 2 as in the previous command.
Here’s a sample of what your build.txt file might look like:
This file will have a lot of detailed information about what was included in your build, why something was not included, and how the executable was packaged.
You can also rebuild your executable using the —debug option in addition to using the —log-level option for even more information.
Note: The -y and —clean options are useful when rebuilding, especially when initially configuring your builds or building with Continuous Integration. These options remove old builds and omit the need for user input during the build process.
Additional PyInstaller Docs
The PyInstaller GitHub Wiki has lots of useful links and debugging tips. Most notably are the sections on making sure everything is packaged correctly and what to do if things go wrong.
Assisting in Dependency Detection
The most common problem you’ll see is ImportError exceptions if PyInstaller couldn’t properly detect all your dependencies. As mentioned before, this can happen if you’re using __import__() , imports inside functions, or other types of hidden imports.
Many of these types of problems can be resolved by using the —hidden-import PyInstaller CLI option. This tells PyInstaller to include a module or package even if it doesn’t automatically detect it. This is the easiest way to work around lots of dynamic import magic in your application.
Another way to work around problems is hook files. These files contain additional information to help PyInstaller package up a dependency. You can write your own hooks and tell PyInstaller to use them with the —additional-hooks-dir CLI option.
Hook files are how PyInstaller itself works internally so you can find lots of example hook files in the PyInstaller source code.
Limitations
PyInstaller is incredibly powerful, but it does have some limitations. Some of the limitations were discussed previously: hidden imports and relative imports in entry-point scripts.
PyInstaller supports making executables for Windows, Linux, and macOS, but it cannot cross compile. Therefore, you cannot make an executable targeting one Operating System from another Operating System. So, to distribute executables for multiple types of OS, you’ll need a build machine for each supported OS.
Related to the cross compile limitation, it’s useful to know that PyInstaller does not technically bundle absolutely everything your application needs to run. Your executable is still dependent on the users’ glibc . Typically, you can work around the glibc limitation by building on the oldest version of each OS you intend to target.
For example, if you want to target a wide array of Linux machines, then you can build on an older version of CentOS. This will give you compatibility with most versions newer than the one you build on. This is the same strategy described in PEP 0513 and is what the PyPA recommends for building compatible wheels.
In fact, you might want to investigate using the PyPA’s manylinux docker image for your Linux build environment. You could start with the base image then install PyInstaller along with all your dependencies and have a build image that supports most variants of Linux.
Conclusion
PyInstaller can help make complicated installation documents unnecessary. Instead, your users can simply run your executable to get started as quickly as possible. The PyInstaller workflow can be summed up by doing the following:
- Create an entry-point script that calls your main function.
- Install PyInstaller.
- Run PyInstaller on your entry-point.
- Test your new executable.
- Ship your resulting dist/ folder to users.
Your users don’t have to know what version of Python you used or that your application uses Python at all!