技術背景
當我們創建一個python項目，最終的成果如果希望用戶能夠不依賴於python源代碼也能夠正常的執行，就會比較的人性化。因為源代碼數量眾多，很難讓每個用戶都自行管理所有的源代碼，因此我們需要對源碼進行編譯構建。對於使用場景不是很復雜的，我們可以直接做成一個可執行文件，這樣開發者只需要維護可執行文件的功能正常，以及對於各種平台的兼容性較好，這就可以了。這里我們介紹如何使用pyinstaller去通過python源碼構造一個可執行文件。
pyinstaller的安裝
我們還是正常的使用pip來進行python包的管理即可：
[dechin@dechin-manjaro installer]$ python3 -m pip install pyinstaller
Collecting pyinstaller
Downloading pyinstaller-4.2.tar.gz (3.6 MB)
|████████████████████████████████| 3.6 MB 18 kB/s
Installing build dependencies ... done
Getting requirements to build wheel ... done
Preparing wheel metadata ... done
Collecting pyinstaller-hooks-contrib>=2020.6
Downloading pyinstaller_hooks_contrib-2021.1-py2.py3-none-any.whl (181 kB)
|████████████████████████████████| 181 kB 13 kB/s
Collecting altgraph
Downloading altgraph-0.17-py2.py3-none-any.whl (21 kB)
Requirement already satisfied: setuptools in /home/dechin/anaconda3/lib/python3.8/site-packages (from pyinstaller) (50.3.1.post20201107)
Building wheels for collected packages: pyinstaller
Building wheel for pyinstaller (PEP 517) ... done
Created wheel for pyinstaller: filename=pyinstaller-4.2-py3-none-any.whl size=2413076 sha256=29c4148e9bcda0a6b08f10c1ee3c48f3dd90992787d01b54d1e920b5954f8fd4
Stored in directory: /home/dechin/.cache/pip/wheels/65/6f/54/0f682e8590de992d07a17ce07282267734cb150e537dfc4390
Successfully built pyinstaller
Installing collected packages: pyinstaller-hooks-contrib, altgraph, pyinstaller
Successfully installed altgraph-0.17 pyinstaller-4.2 pyinstaller-hooks-contrib-2021.1
下載安裝成功后，可以運行幫助命令來測試一下：
[dechin@dechin-manjaro installer]# pyinstaller -h
usage: pyinstaller [-h] [-v] [-D] [-F] [--specpath DIR] [-n NAME]
[--add-data <SRC;DEST or SRC:DEST>]
[--add-binary <SRC;DEST or SRC:DEST>] [-p DIR]
[--hidden-import MODULENAME] [--additional-hooks-dir HOOKSPATH]
[--runtime-hook RUNTIME_HOOKS] [--exclude-module EXCLUDES] [--key KEY]
[-d {all,imports,bootloader,noarchive}] [-s] [--noupx]
[--upx-exclude FILE] [-c] [-w]
[-i <FILE.ico or FILE.exe,ID or FILE.icns or "NONE">]
[--version-file FILE] [-m <FILE or XML>] [-r RESOURCE] [--uac-admin]
[--uac-uiaccess] [--win-private-assemblies] [--win-no-prefer-redirects]
[--osx-bundle-identifier BUNDLE_IDENTIFIER] [--runtime-tmpdir PATH]
[--bootloader-ignore-signals] [--distpath DIR] [--workpath WORKPATH]
[-y] [--upx-dir UPX_DIR] [-a] [--clean] [--log-level LEVEL]
scriptname [scriptname ...]
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.
optional arguments:
-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)
-a, --ascii Do not include unicode encoding support (default: included if
available)
--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, ERROR, CRITICAL (default: INFO).
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 Name to assign to the bundled app and spec file (default: first
script's basename)
What to bundle, where to search:
--add-data <SRC;DEST or SRC:DEST>
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
--hidden-import MODULENAME, --hiddenimport MODULENAME
Name an import not visible in the code of the script(s). 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.
--key KEY The key used to encrypt Python bytecode.
How to generate:
-d {all,imports,bootloader,noarchive}, --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.
-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 Mac OS X specific options:
-c, --console, --nowindowed
Open a console window for standard i/o (default). On Windows this
option will have no effect if the first script is a '.pyw' file.
-w, --windowed, --noconsole
Windows and Mac OS X: do not provide a console window for standard
i/o. On Mac OS X this also triggers building an OS X .app bundle.
On Windows this option will be set if the first script is a '.pyw'
file. This option is ignored in *NIX systems.
-i <FILE.ico or FILE.exe,ID or FILE.icns or "NONE">, --icon <FILE.ico or FILE.exe,ID or FILE.icns or "NONE">
FILE.ico: apply that icon to a Windows executable. FILE.exe,ID,
extract the icon with ID from an exe. FILE.icns: apply the icon to
the .app bundle on Mac OS X. Use "NONE" to not apply any icon,
thereby making the OS to show some default (default: apply
PyInstaller's icon)
Windows specific options:
--version-file FILE add a version resource from FILE to the exe
-m <FILE or XML>, --manifest <FILE or XML>
add manifest FILE or XML to the exe
-r RESOURCE, --resource RESOURCE
Add or update a resource to a Windows executable. The RESOURCE is
one to four items, FILE[,TYPE[,NAME[,LANGUAGE]]]. FILE can be a
data file or an exe/dll. For data files, at least TYPE and NAME
must be specified. LANGUAGE defaults to 0 or may be specified as
wildcard * to update all resources of the given TYPE and NAME. For
exe/dll files, all resources from FILE will be added/updated to
the final executable if TYPE, NAME and LANGUAGE are omitted or
specified as wildcard *.This option can be used multiple times.
--uac-admin Using this option creates a Manifest which will request elevation
upon application restart.
--uac-uiaccess Using this option allows an elevated application to work with
Remote Desktop.
Windows Side-by-side Assembly searching options (advanced):
--win-private-assemblies
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.
--win-no-prefer-redirects
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 X specific options:
--osx-bundle-identifier BUNDLE_IDENTIFIER
Mac OS X .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)
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.
--bootloader-ignore-signals
Tell the bootloader to ignore signals rather than forwarding them
to the child process. Useful in situations where e.g. a supervisor
process signals both the bootloader and child (e.g. via a process
group) to avoid signalling the child twice.
如果覺得這份官方的幫助文檔過於冗余，可以參考下一個章節中的縮略版幫助文檔。
構造python測試實例
因為可執行文件的自身內容都是固定的，只能通過配置文件或者是命令行的輸入參數來進行傳參，因此我們構造python文件的時候主要從命令行的這個角度來出發，通過讀取命令行的輸入參數來決定python項目的輸出。我們這里構造的是一個名為pye的項目，意思是python executable，也就是可執行的python項目，項目的功能是計算一個入參的平方：
# pye.py
import sys
if sys.argv[1] == '-h':
print ('pye: Test the executable python project')
print (' -h')
print ('\t The help message of pye.')
print (' -p2 number')
print ('\t Calculate the power to of input number.')
if sys.argv[1] == '-p2':
print ('The power2 of number {} is : {}'.format(sys.argv[2], float(sys.argv[2]) ** 2))
在上述構造中我們區分了-h和-p2兩種參數類型，其中-h是指幫助文檔，輸出如下所示：
[dechin@dechin-manjaro installer]$ python3 pye.py -h
pye: Test the executable python project
-h
The help message of pye.
-p2 number
Calculate the power to of input number.
而-p2是標識需要計算平方的入參的參數：
[dechin@dechin-manjaro installer]$ python3 pye.py -p2 2
The power2 of number 2 is : 4.0
[dechin@dechin-manjaro installer]$ python3 pye.py -p2 5
The power2 of number 5 is : 25.0
pyinstaller簡單示例
由於官方的幫助文檔內容太多，不太方便入門，這里我們找了一份簡單常用的總結文檔（表格來自於參考鏈接1）：
了解了基本的使用方法之后，可以針對我們上述編寫的pye.py的項目進行編譯構建：
[dechin@dechin-manjaro installer]$ pyinstaller -F pye.py --clean
754 INFO: PyInstaller: 4.2
754 INFO: Python: 3.8.5 (conda)
791 INFO: Platform: Linux-5.9.16-1-MANJARO-x86_64-with-glibc2.10
791 INFO: wrote /home/dechin/projects/2021-python/installer/pye.spec
794 INFO: UPX is not available.
795 INFO: Removing temporary files and cleaning cache in /home/dechin/.cache/pyinstaller
795 INFO: Extending PYTHONPATH with paths
['/home/dechin/projects/2021-python/installer',
'/home/dechin/projects/2021-python/installer']
808 INFO: checking Analysis
808 INFO: Building Analysis because Analysis-00.toc is non existent
808 INFO: Initializing module dependency graph...
810 INFO: Caching module graph hooks...
813 WARNING: Several hooks defined for module 'win32ctypes.core'. Please take care they do not conflict.
814 INFO: Analyzing base_library.zip ...
2945 INFO: Processing pre-find module path hook distutils from '/home/dechin/anaconda3/lib/python3.8/site-packages/PyInstaller/hooks/pre_find_module_path/hook-distutils.py'.
2946 INFO: distutils: retargeting to non-venv dir '/home/dechin/anaconda3/lib/python3.8'
5397 INFO: Caching module dependency graph...
5466 INFO: running Analysis Analysis-00.toc
5487 INFO: Analyzing /home/dechin/projects/2021-python/installer/pye.py
5489 INFO: Processing module hooks...
5489 INFO: Loading module hook 'hook-encodings.py' from '/home/dechin/anaconda3/lib/python3.8/site-packages/PyInstaller/hooks'...
5526 INFO: Loading module hook 'hook-pickle.py' from '/home/dechin/anaconda3/lib/python3.8/site-packages/PyInstaller/hooks'...
5528 INFO: Excluding import of argparse from module pickle
5528 INFO: Loading module hook 'hook-difflib.py' from '/home/dechin/anaconda3/lib/python3.8/site-packages/PyInstaller/hooks'...
5529 INFO: Excluding import of doctest from module difflib
5529 INFO: Loading module hook 'hook-xml.py' from '/home/dechin/anaconda3/lib/python3.8/site-packages/PyInstaller/hooks'...
5600 INFO: Loading module hook 'hook-sysconfig.py' from '/home/dechin/anaconda3/lib/python3.8/site-packages/PyInstaller/hooks'...
5609 INFO: Loading module hook 'hook-_tkinter.py' from '/home/dechin/anaconda3/lib/python3.8/site-packages/PyInstaller/hooks'...
5693 INFO: checking Tree
5693 INFO: Building Tree because Tree-00.toc is non existent
5693 INFO: Building Tree Tree-00.toc
5699 INFO: checking Tree
5699 INFO: Building Tree because Tree-01.toc is non existent
5699 INFO: Building Tree Tree-01.toc
5733 INFO: checking Tree
5733 INFO: Building Tree because Tree-02.toc is non existent
5734 INFO: Building Tree Tree-02.toc
5736 INFO: Loading module hook 'hook-distutils.py' from '/home/dechin/anaconda3/lib/python3.8/site-packages/PyInstaller/hooks'...
5736 INFO: Loading module hook 'hook-xml.etree.cElementTree.py' from '/home/dechin/anaconda3/lib/python3.8/site-packages/PyInstaller/hooks'...
5737 INFO: Loading module hook 'hook-lib2to3.py' from '/home/dechin/anaconda3/lib/python3.8/site-packages/PyInstaller/hooks'...
5757 INFO: Loading module hook 'hook-heapq.py' from '/home/dechin/anaconda3/lib/python3.8/site-packages/PyInstaller/hooks'...
5759 INFO: Excluding import of doctest from module heapq
5759 INFO: Loading module hook 'hook-distutils.util.py' from '/home/dechin/anaconda3/lib/python3.8/site-packages/PyInstaller/hooks'...
5760 INFO: Excluding import of lib2to3.refactor from module distutils.util
5760 INFO: Loading module hook 'hook-multiprocessing.util.py' from '/home/dechin/anaconda3/lib/python3.8/site-packages/PyInstaller/hooks'...
5761 INFO: Excluding import of test from module multiprocessing.util
5761 INFO: Excluding import of test.support from module multiprocessing.util
5768 INFO: Looking for ctypes DLLs
5791 INFO: Analyzing run-time hooks ...
5794 INFO: Including run-time hook '/home/dechin/anaconda3/lib/python3.8/site-packages/PyInstaller/hooks/rthooks/pyi_rth_multiprocessing.py'
5799 INFO: Looking for dynamic libraries
6299 INFO: Looking for eggs
6300 INFO: Python library not in binary dependencies. Doing additional searching...
6315 INFO: Using Python library /home/dechin/anaconda3/lib/libpython3.8.so.1.0
6321 INFO: Warnings written to /home/dechin/projects/2021-python/installer/build/pye/warn-pye.txt
6352 INFO: Graph cross-reference written to /home/dechin/projects/2021-python/installer/build/pye/xref-pye.html
6361 INFO: checking PYZ
6361 INFO: Building PYZ because PYZ-00.toc is non existent
6361 INFO: Building PYZ (ZlibArchive) /home/dechin/projects/2021-python/installer/build/pye/PYZ-00.pyz
6647 INFO: Building PYZ (ZlibArchive) /home/dechin/projects/2021-python/installer/build/pye/PYZ-00.pyz completed successfully.
6649 INFO: checking PKG
6650 INFO: Building PKG because PKG-00.toc is non existent
6650 INFO: Building PKG (CArchive) PKG-00.pkg
10882 INFO: Building PKG (CArchive) PKG-00.pkg completed successfully.
10883 INFO: Bootloader /home/dechin/anaconda3/lib/python3.8/site-packages/PyInstaller/bootloader/Linux-64bit/run
10883 INFO: checking EXE
10884 INFO: Building EXE because EXE-00.toc is non existent
10884 INFO: Building EXE from EXE-00.toc
10884 INFO: Appending archive to ELF section in EXE /home/dechin/projects/2021-python/installer/dist/pye
10914 INFO: Building EXE from EXE-00.toc completed successfully.
執行成功編譯構建的方法之后，會在本地產生一些編譯的路徑，如build和dist等，完整的路徑和文件清單如下所示：
[dechin@dechin-manjaro installer]$ tree
.
├── build
│ └── pye
│ ├── Analysis-00.toc
│ ├── base_library.zip
│ ├── EXE-00.toc
│ ├── PKG-00.pkg
│ ├── PKG-00.toc
│ ├── PYZ-00.pyz
│ ├── PYZ-00.toc
│ ├── Tree-00.toc
│ ├── Tree-01.toc
│ ├── Tree-02.toc
│ ├── warn-pye.txt
│ └── xref-pye.html
├── dist
│ └── pye
├── __pycache__
│ └── pye.cpython-38.pyc
├── pye.py
└── pye.spec
4 directories, 16 files
我們可以看到在dist目錄下有一個單獨的可執行文件，這個就是我們最終想要的文件了。我們可以在dist目錄下執行運行這個文件：
[dechin@dechin-manjaro dist]$ ./pye -h
pye: Test the executable python project
-h
The help message of pye.
-p2 number
Calculate the power to of input number.
[dechin@dechin-manjaro dist]$ ./pye -p2 5
The power2 of number 5 is : 25.0
經過驗證所有的功能都正常。那么最后還缺一步，就是我們如果想要通過項目名 -參數表示 參數這樣的方法來運行我們的項目的話，就需要把這個可執行文件添加到系統路徑中。最常用的方法其實是直接將該可執行文件拷貝到/usr/bin/目錄下，這樣該可執行文件就可以直接使用，不需要在前面加上路徑就能運行。當然，為了執行這個操作，我們首先需要切換到root帳號下，再執行文件拷貝操作：
[dechin-root dist]# cp pye /usr/bin/
拷貝完成后，直接運行：
[dechin-root dist]# pye -h
pye: Test the executable python project
-h
The help message of pye.
-p2 number
Calculate the power to of input number.
[dechin-root installer]# pye -p2 7
The power2 of number 7 is : 49.0
我們發現所有的功能都是正常的，並且在普通帳號下也是可以正常使用的。到這里為止，我們就達到了項目所預期的效果。
總結概要
通過pyinstaller我們可以將一個python項目打包編譯構建成一個可執行文件，然后將該可執行文件放置到一個系統路徑下，使得系統可以不需要路徑也能夠識別到這個可執行文件，這樣我們就可以僅配置一些輸入文件或者命令行的入參，來運行我們的項目。
版權聲明
本文首發鏈接為：https://www.cnblogs.com/dechinphy/p/pyinstaller.html
作者ID：DechinPhy
更多原著文章請參考：https://www.cnblogs.com/dechinphy/