Python study notes: PyInstaller (exe package)

PyInstaller Python program may be packaged into a separate exe program to run, performed only when the user uses the exe file, do not need to install Python and other packages can be run on the machine. In addition, PyInstaller compared to other packaged applications, such as py2exe, most of the time more convenient to use, a few simple commands via the command line can be packaged, of course, when you need to package a large and complex program, the use of which pack the program may not have too much difference, this time depends on personal habits and hobbies.

pip安装PyInstaller：pip install pyinstaller

pip更新PyInstaller：pip install --upgrade pyinstaller

pypi下载PyInstaller：https://pypi.org/project/PyInstaller/#files

Note: the need for additional installation of two additional modules windows installed PyInstaller, pywin32 or pypiwin32, and pefile, if you use pip to install, but not when you install pywin32, will automatically install pypiwin32, pefile no time will be automatically installed.

 

Simple packaging commands

pyinstaller [-F/-D] [-w/-c] [-i xxx.ico] xxx.py/xxx.spec

 

• xxx.py/xxx.spec: need to package the main program file or a file spec. spec file is automatically generated when using py file is packaged in the same path, the contents of the spec is also based on the content inputted to the command line generated command may be used pyi-makespec [options] xxx.py to generate a pure spec file, instead of running packaging operations.
• -F / - onefile: The entire program is packaged as a exe file needs to be noted that the pattern generated by the -D exe program compared to, on the start rate will be a little slower because it needs to extract the exe file and generate a unique temporary environment to run the program, will be automatically deleted when you close this temporary environment environment, program -D decompression mode itself is good, do not need to run the complete delete operation, when the program is relatively large, this difference is very obvious.
• -D / - onedir: default option, and F / - onefile opposite effect parameters will be packaged as a file folder, exe files in the folder that contains the launcher and other dependent resource files and DLL files.
• -w: When expressed after the program runs hidden command line window, when you do not need to use the command line window as the program I / O, such as GUI, you can use this parameter options.
• -c: the default option, as opposed to -w, providing a command I / O line window.
• -i / - icon: Specifies the exe icon.

In general, most of the program, especially some small programs, can successfully use this command packaging, and also less than other complex parameter options. If you need additional knowledge points, some of the following points may refer to the following (these points are found on official documents, some not proven, wrong please correct me):

Specify command-line parameters is packaged options:

1. build folder: run will generate a build folder in the same path, the role of this folder is equivalent to the work space PyInstaller, PyInstaller run relevant files and logs are in this folder, you can delete the complete package.
2. dist folder: After the run is completed will generate a dist folder in the same path, there is a file with the same name as the program folder, packaged exe program in this folder under this folder.
3. Multi-py file: If the command line specified py more than one file, such as "pyinstaller xxx1.py xxx2.py", pyinstaller will be followed by analysis and execution, and the first name as py files in folders and spec and dist name of the program.
4. Other common parameter options:
   • --specpath DIR: Specifies the path to generate the spec file, the default is the current path.
   • -n NAME / - name NAME: Specifies the spec file and the name of the program, the default is the name of the incoming py script or spec file.
   • -h / - help: show PyInstaller help information.
   • -v / - version: display PyInstaller version information.
   • --distpath DIR: directory dist designated generation, the default is "./dist".
   • --workpath WORKPATH: Specifies the working directory pyinstaller, that build folder, the default is "./build".
   • -y / - noconfirm: Do not ask when replacing output directory, the default output directory is "SPECPATH / dist / SPECNAME".
   • --upx-dir UPX_DIR: Specifies the UPX program path, the default is "execution path", ie double-click a file, the system automatically find the path of the corresponding program. UPX is a compression program, exe can be compressed into a zip file format and compression efficiency is very high, if the packaged exe program is very large, in order to avoid the client to download files much of a problem, you can use the UPX tool.
   • --noupx: does not require the UPX (even if available).
   • -a / - ascii: does not support Unicode, the default is to support (if available).
   • --clean: Clear the cache before pyinstaller begin and delete temporary files (typically stored in C: \ Users \ Administrator \ AppData \ Roaming \ pyinstaller).
   • --log-level LEVEL: log level specifying the print, the default is INFO, log level there is: TRACE, DEBUG, INFO, WARN , ERROR, CRITICAL. If you encounter a problem when packaging, in order to facilitate locating the problem, you can use this parameter to see a certain level of log information.
5. Data binding and search-related parameter options:
   • --add-data SRC; DEST: Specifies the need to add non-binary file path or folder path, such as images and pdf files, this option can be used multiple times. This command is actually will need to copy the file or folder at the path specified in -D mode, you can manually copy the past to see the situation of their own after the program is completed package.
   • --add-binary SRC; DEST: binary path specified needs to be added, such as DLL files, dynamic link library, or share files and other objects, this option can be used multiple times. Like -add-data command, the function is a copy of the data.
   • -p DIR / - paths DIR: specify where import statements (like PYTHONPATH), you can use multiple paths between a colon ":" Connection, or repeatedly use this option to be specified.
   • --hidden-import MODULENAME / - hiddenimport MODULENAME : implicitly imported module script specified needs, such as the imported modules __import __, imp.find_module (), exec , eval , etc. statements, these modules are not found PyInstaller the need to manually specify import, this option can be used multiple times.
   • --additional-hooks-dir HOOKSPATH: specify additional hook file (the file can be py) search path, the role of these documents is to change some of the Python or other execution logic of the original library functions or variables PyInstaller run time (not these libraries will change the code itself) in order to successfully complete package, this option can be used multiple times.
   • --runtime-hook RUNTIME_HOOKS: Specifies hook run custom file path (the file may be py) in a packed and exe program, when running the exe program, before the specified file will hook all code modules and operation, including the main documents to meet the special requirements of the operating environment, this option can be used multiple times.
   • --exclude-module EXCLUDES: designation can be ignored or optional module package, because only certain modules PyInstaller according to its own logic to find these modules for exe program itself is not used, but still in the log tips "module not found", this log can not control, or use this option to specify parameters do not import, this option can be used multiple times.
   • --key KEY: Specifies the Python bytecode encryption key, key is a string of 16 characters.
6. -D program run mode: When running the program, in fact, began running a pyinstaller generate boot loader bootloader, bootloader is generated based on different operating systems, when you run the bootloader, will create a temporary environment for running Python Python program, so do not use Python installation exe program can run this program.
7. -F mode of operation of the program: there will be a BootLoader, but the operating system will create a folder named _MEIxxxxxx, used as a temporary operating environment of this program (not just Python environment), this is a random number xxxxxx . -F startup mode because of the time need to extract and copy the files to a temporary resource dependent and operating environment _MEIxxxxxx, so the start-up speed is slower than -D-mode program after the end of the run will delete temporary operating environment folder. Linux and related systems, there may be "no-execution" option, but for -F-mode programs are not compatible. Since _MEIxxxxxx is unique, so you can run multiple programs at the same time, non-interference when multiple programs. If the program crashes, or forcibly ended (such as killed in the Windows Task Manager in the process), _ MEIxxxxxx folder is not deleted, so frequent crashes or the end of the process will lead to more _MEIxxxxxx folders, will be very occupied disk space, you can use --runtime-temdir designated storage location of _MEIxxxxxx. -F model has encountered a permissions problem if you are running, you can use an alternative mode program -D.
8. shell script / batch script: using the command-line package, all the command information may need to specify parameter options are many, this time may need to be performed, including options to specify these parameters, you are placed in a shell script or batch file performed.
9. Runtime information:
   • __file__: All modules based on the use of the code __file__ property, expressed in the source runtime is the absolute path to the current script, but after the current module is packaged module name (ie file name xxx.py).
   • sys.frozen: source runtime Without this attribute, the program package adds this attribute is True.
   • sys._MEIPASS: source runtime Without this attribute, the program package adds this attribute indicates the absolute path of the program to run. For -D-mode programs, represents the absolute path to the folder where the program exe for -F mode program represents the _MEIxxxxxx folder absolute path, _MEIxxxxxx temporary files created after the operating environment for the extracting exe folder name, for exe program every time you run it, it is unique.
   • sys.excutable: Code runtime interpreter represents the absolute path operation, such as C: \ Python36 \ python.exe, the packaged program exe program is the absolute path of the file, this is used to locate the real position of the user running the program .
   • sys.argv [0]: In general is the absolute path to run the program, but in different ways on different platforms or start the program, will be different, such as a program run by the sys.argv symbolic link [0] is the symbolic name instead of the real program path.
10. Modify data files : - add-data which form data files by copying, modifications -D mode if at run time, then the corresponding data file is really been modified, but in the mode -F, Because each run will create a temporary operating environment alone, but also to modify the contents of the temporary operation of the content environment, and runs automatically deleted after the temporary operating environment, so this data file can not change the data in the exe file directly, which means that each time you run the program, the data file will be the exe program that the original copy, modify content will temporarily shut down the operating environment as deleted, and will not be synchronized to the exe program.
11. When an error occurs:
    
    • When happen "module not found" warning, in fact, many messages could not find the corresponding modules do not have control, but PyInstaller according to its own logic to find because they are not with your final proceedings.
    • When you import a failure occurs, this is the real mistake, you need to pay attention to and solve problems.
    • When the package successfully, and the middle of any warning probably "--hidden-import =" The problem did not occur, but that it can not find a module running the program, and when __import __, imp.find_module (), exec when eval or Python / C API, pyinstaller not automatically lead into the package to which these involve, these packages need to use "--hidden-import =" specifies the specific packet needs to import a.
    •  --runtime-hook = xxx.py py specified in the main program will be sequentially before running the script main packaged, can be used to change some of the functions or variables, to meet the requirements of the particular scene.

 

spec is packaged profiles

1. Generating spec file: PYI-makespec [Options] xxx.py [OTHER scripts ...], nothing can be specified when generating spec file, and then individually configured to generate spec file, the file spec default mode -D you can also specify the spec file generated -F mode. Of course, you can specify the parameters of good will in the first option, since you only maintain spec files.
2. Parameter options: Under the command line parameter options and spec file generation mode execution PyInstaller package is exactly the same.
3. File type spec: the spec file is actually a py file, edit it directly as a py file to use.
4. spec file advantages: generally speaking, the direct use PyInstaller command line can be packaged directly, but use the following spec file will be convenient if:
   • Programs need to bind some data files, you can use a list of variables to be specified individually spec file, readability and maintainability would be much higher.
   • PyInstaller need to include some of the dynamic link library does not know, such as: .dll / .so files, can also be used alone to specify a list of variables in the spec file.
   • You need to add some runtime options, such as hook file to an executable file.
5. spec files:
   • a: Examples Analysis class requirements for introducing and passing various scripts dependency analysis procedures. a content includes the following four parts: scripts, Python scripts which can enter the command line; Pure, the program code file required pure Python module; Binaries, program modules than Python code file needs, including --add -binary parameters specified content; DATAS, non-binary files, including --add-data parameter specifies the content.
   • pyz: Examples PYZ is .pyz a file that contains all the Python modules all pure.
   • exe: Examples EXE class, this class is used to handle and PYZ Analysis of the results, is used to generate the final executable program exe.
   • coll: Examples COLLECT class used to create the output directory. In -F mode, there is no COLLECT example and all script files and binary modules are included in the finally generated exe file.
6. Analysis The first argument: is a list of scripts that may be passed multiple py script, the same effect is specified multi-py file with the command line, which is more than one py file, such as "pyinstaller xxx1.py xxx2.py", pyinstaller will followed by analysis and execution, and the first py name as the name of the folder and program files in the spec file and dist.
7. Analysis parameters datas: i.e. to add a data file, the command is --add-data, spec file is Analysis of datas = [] parameter, a DATAS elements is a list of tuples, each tuple has two elements, must It is a string type, the first element of the tuple of data files or folders, files or folders which the second element of the tuple is run position. For example: datas = [( '.' 'Src / README.txt',),], may be written in the command line: pyinstaller --add-data 'src / README.txt ;.' myscript.py, represents when packaged adding a file src / README.txt (copy) with respect to the root directory spec file, the file is specified with respect to the search spec, it is not intended to packaged exe program path. Can also use wildcards: datas = [( '/mygame/sfx/*.mp3' , 'sfx')], represents all .mp3 files under / mygame / sfx / directories to copy sfx folder. You may be added to the entire folder: datas = [( '/ mygame / data', 'data')], showing the clip / mygame / data file and all the files to copy the data folder.
8. Analysis parameters binaries: add binary file, the effect is the same command --add-binary, is also a list of parameters as defined manner and datas.
9. Analysis参数hiddenimports：同命令“--hidden-import MODULENAME/--hiddenimport MODULENAME”。
10. Analysis parameters hookspath: with the command "--additional-hooks-dir HOOKSPATH" .
11. Analysis参数runtime_hooks：同命令“--runtime-hook RUNTIME_HOOKS”。
12. Analysis parameters excludes: with the command "--exclude-module EXCLUDES".
13. exe parameter console: setting whether to display command line window, command and -w / -c same role.
14. exe parameters icon: Setup icon, and command -i / - the same icon effect. In some cases, direct execution spec generated when "pyinstaller xxx.py" in this parameter is not need to manually add, the string parameter value is the path of the picture.
15. PyInstaller global variables: global variables can be used in the spec file.
    • DISTPATH: relative path dist folder, if --distpath parameter option is specified, the specified value of the parameter used.
    • HOMEPATH: absolute path pyinstaller looking for, generally site-packages absolute path to the file folder of the Python interpreter.
    • SPEC: spec file path specified on the command line.
    • SPECPATH: first value os.path.split (SPEC) of.
    • specnm: filename spec file, without the file type suffix.
    • workpath: relative path to build a folder, if workpath = parameter option is specified, the use of this value is specified.
    • WARNFILE: the full path to the build folder warning file, usually warn-myscript.txt
16. Specify the same parameters: When the command line and specify the same spec parameter options, then the command line parameter options are ignored.

 

Problems encountered and solutions:

1. Problem Description:

Times are as follows Packaging exception:

File "c:\python36\lib\site-packages\PyInstaller\hooks\pre_safe_import_module\hook-setuptools.extern.six.moves.py", line 34, in pre_safe_import_module
for real_module_name, six_module_name in real_to_six_module_name.items():
AttributeError: 'str' object has no attribute 'items'

solution:

Use the command "pip install --upgrade setuptools" update-party libraries setuptools

 

--additional-hooks-dir HOOKSPATH