PyInstaller 完美打包 Python 指令碼，輸出結構清晰、便於二次編輯的打包程式
引入問題
如果我要寫一個 Python 專案，打包成 exe 執行（方便在沒有 Python 的電腦上使用），我需要打包出的根目錄結構美觀，沒有多餘的、雜亂的依賴檔案在那裡礙眼，而且需要在發現 bug 時，我還需要能夠修改裡面的程式碼後，無需再次打包，就能正常執行，該怎麼做呢？
就以一個 Hello 專案為例，記一下我找到的完美方法。
首先，新建專案資料夾，寫一個 hello.py：
用 PyInstaller 把 hello.py 打包，pyinstaller ./hello.py 命令會得到 build 和 dist 資料夾，以及 hello.spec 檔案：
其中：
build資料夾是存放打包時臨時檔案用的dist資料夾存放了打包好的應用hello.spec內容是PyInstaller根據我們的命令列生成的打包引數
開啟 dist/hello 資料夾，可以看到我們打包好的 hello.exe 躺在一堆依賴檔案之間，非常醜陋：
我們的目標，就是要把這些依賴包都移到一個子資料夾中，讓打包資料夾變得整潔，同時讓程式正常執行。
最後我們可以打包成這個樣子：
首先，所有的依賴模組都被移動到了 libs 資料夾，整個打包根目錄清清爽爽，只留下了必要的 python310.dll 和 base_library.zip。
其次，如你所見，這個程式的脾氣不是太好，出口成髒，我們希望使用者在拿到這個開源程式時，可以修改指令碼的內容，不需要重新打包就能直接從 hello.exe 執行。因此我們要把 hello.exe 做成程式入口，實際的邏輯寫在 hello_main.py ，同時要確保 hello_main.py 中的依賴都被正確打包到 libs 資料夾。
我們一步步解決。
第一步：自定義依賴包位置
生成 spec 檔案
達到目的的關鍵在於用命令列打包時自動生成的 hello.spec ，它的本質是一個 python 檔案，pyinstaller 有兩種執行模式：
pyinstaller hello.spec會使用spec檔案中的設定進行打包pyinstaller hello.py <other args>根據命令列引數自動生成spec檔案，再依據使用spec檔案中的設定進行打包
pyinstaller 在打包時，實際上是在做了一些準備工作後，直接執行了 spec 檔案裡的 Python 程式碼。
相比於給命令列新增引數，直接編輯 spec 檔案，在裡面儲存引數，更優雅，更方便操作。
除了直接打包腳，本檔案自動生成 spec 設定，還可以通過執行 pyi-makespec hello.py 不打包，只生成 spec 設定。
解釋 spec 檔案
開啟 hello.spec 檔案，有如下內容（已作註釋）：
# -*- mode: python ; coding: utf-8 -*-
block_cipher = None
# 這一部分負責收集你的指令碼需要的所有模組和檔案。的；hiddenimports 引數可以指定一些 PyInstaller 無法自動檢測到的模組。
a = Analysis(
['hello.py'], # 指定要打包的 Python 指令碼的路徑（可以是相對路徑）
pathex=[], # 用來指定模組搜尋路徑
binaries=[], # 包含了動態連結庫或共用物件檔案，會在執行之後自動更新，加入依賴的二進位制檔案
datas=[], # 列表，用於指定需要包含的額外檔案。每個元素都是一個元組：（檔案的源路徑, 在打包檔案中的路徑)
hiddenimports=[], # 用於指定一些 PyInstaller 無法自動檢測到的模組
hookspath=[], # 指定查詢 PyInstaller 勾點的路徑
hooksconfig={}, # 自定義 hook 設定，這是一個字典，一行註釋寫不下，此處先不講
runtime_hooks=[], # 指定執行時 hook，本質是一個 Python 指令碼，hook 會在你的指令碼執行前執行，可用於準備環境
excludes=[], # 用於指定需要排除的模組
win_no_prefer_redirects=False,
win_private_assemblies=False,
cipher=block_cipher,
noarchive=False,
)
# 除此之外，a 還有一些沒有列出的屬性：
# pure 是一個列表，包含了所有純 Python 模組的資訊，每個元素是一個元組，包含了：模組名, pyc路徑, py 路徑，這些模組會被打包到一個 .pyz 檔案中。
# scripts 是一個列表，包含了你的 Python 指令碼的資訊。每個元素是一個元組，其中包含了指令碼的內部名，指令碼的源路徑，以及一些後設資料。這些指令碼會被打包到一個可執行檔案中。
# pyz 是指生成的可執行檔案的名稱。它是由 PyInstaller 用來打包 Python 程式和依賴項的主要檔案。
# 建立 pyz 檔案，它在執行時會被解壓縮到臨時目錄中，然後被載入和執行。它會被打包進 exe 檔案
pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)
# 建立 exe 檔案
exe = EXE(
pyz, # 包含了所有純 Python 模組
a.scripts, # 包含了主指令碼及其依賴
[], # 所有需要打包到 exe 檔案內的二進位制檔案
exclude_binaries=True, # 若為 True，所有的二進位制檔案將被排除在 exe 之外，轉而被 COLLECT 函數收集
name='hello', # 生成的 exe 檔案的名字。
debug=False, # 打包過程中是否列印偵錯資訊？
bootloader_ignore_signals=False,
strip=False, # 是否移除所有的符號資訊，使打包出的 exe 檔案更小
upx=True, # 是否用 upx 壓縮 exe 檔案
console=True, # 若為 True 則在控制檯視窗中執行，否則作為後臺程序執行
disable_windowed_traceback=False,
argv_emulation=False,
target_arch=None,
codesign_identity=None,
entitlements_file=None,
)
# 這個物件包含了所有需要分發的檔案
# 包括 EXE 函數建立的 exe 檔案、所有的二進位制檔案、zip 檔案（如果有的話）和資料檔案
coll = COLLECT(
exe,
a.binaries,
a.zipfiles,
a.datas,
strip=False,
upx=True,
upx_exclude=[],
name='hello', # 生成的資料夾的名字
)
加入 Hook
通過對 spec 檔案的瞭解，我們知道了，可以在 a.runtimehooks 列表中加入 python 指令碼 hook ，它會在我們的主程式碼執行之前執行，為我們準備環境。
在這個 hook 裡面，我們就可以修改 sys.path ，自定義 Python 查詢模組的路徑，或者環境變數
那我們就寫一個 hook.py
import sys
from pprint import pprint
print(f'\n\n模組查詢路徑：')
pprint(sys.path)
print('\n')
然後，用 pyinstaller hello.spec 進行打包，再執行得到的 hello.exe，得到如下輸出：
可見 hook.py 確實在 hello.py 之前執行了，且列印出了 sys.path ，即模組查詢路徑，有三個：
dist/hello/base_library.zip這個是程式所在目錄的 base_library.zip 檔案dist/hello/lib-dynload這個是執行程式時動態生成的dist/hello/這個是程式所在目錄
hook 修改 sys.path
因此，我們就可以在打包輸出資料夾中新建一個 libs 資料夾，將所有的依賴檔案全都放進去，然後在 hook.py 裡把 libs 路徑加入 sys.path ，然後我們的指令碼執行時就正確搜尋到依賴包了。
改寫 hook.py
import sys
from pathlib import Path
from pprint import pprint
BASE_DIR = Path(__file__).parent
for p in sys.path.copy():
relative_p = Path(p).relative_to(BASE_DIR)
new_p = BASE_DIR / 'libs' / relative_p
sys.path.insert(0, str(new_p))
print(f'\n\n模組查詢路徑：')
pprint(sys.path)
print('\n')
然後，用 pyinstaller hello.spec 進行打包，再執行得到的 hello.exe，得到如下輸出：
從輸出可以看到模組查詢路徑，已經修改成功，新增了 libs 資料夾。
既然模組查詢路徑新增成功。那我們就 手動 把所有的依賴檔案都移動到 libs 子資料夾中，再執行 hello.exe ，完美執行：
需要注意的是：由於
hook也是python指令碼，執行hook需要python環境，所以python310.dll和base_library.zip不能移動到libs資料夾中。我用的
Python版本是3.10，所以會有一個python310.dll，具體的檔名會隨你安裝的Python版本而變化
檢視依賴目標位置
雖然我們在打包後將依賴檔案移動到 libs 資料夾，程式能正常執行，但是我們肯定不希望每次打包都要 手動 移動一次。
實際上我們可以在 spec 檔案中定義依賴檔案和二進位制檔案的存放位置。
pyinstaller 在執行 spec 檔案中的程式碼時，自動分析找到所需的依賴檔案後，會把他們的目標路徑和原始路徑寫到 a.binaries ，我們可以把它列印出來看一下。
修改 hello.spec 檔案
# -*- mode: python ; coding: utf-8 -*-
block_cipher = None
a = Analysis(
['hello.py'],
pathex=[],
binaries=[],
datas=[],
hiddenimports=[],
hookspath=[],
hooksconfig={},
runtime_hooks=['hook.py'],
excludes=[],
win_no_prefer_redirects=False,
win_private_assemblies=False,
cipher=block_cipher,
noarchive=False,
)
from pprint import pprint
pprint(a.binaries) # 列印 a.binaries
pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)
exe = EXE(
pyz,
a.scripts,
[],
exclude_binaries=True,
name='hello',
debug=False,
bootloader_ignore_signals=False,
strip=False,
upx=True,
console=True,
disable_windowed_traceback=False,
argv_emulation=False,
target_arch=None,
codesign_identity=None,
entitlements_file=None,
)
coll = COLLECT(
exe,
a.binaries,
a.zipfiles,
a.datas,
strip=False,
upx=True,
upx_exclude=[],
name='hello',
)
然後，用 pyinstaller hello.spec 進行打包過程中得到如下輸出：
[('api-ms-win-crt-runtime-l1-1-0.dll',
'C:\\Portable_library\\java\\jdk-14.0.1\\bin\\api-ms-win-crt-runtime-l1-1-0.dll',
'BINARY'),
('python310.dll',
'C:\\Users\\Haujet\\AppData\\Local\\Programs\\Python\\Python310\\python310.dll',
'BINARY'),
('api-ms-win-crt-heap-l1-1-0.dll',
'C:\\Portable_library\\java\\jdk-14.0.1\\bin\\api-ms-win-crt-heap-l1-1-0.dll',
'BINARY'),
('VCRUNTIME140.dll',
'C:\\Users\\Haujet\\AppData\\Local\\Programs\\Python\\Python310\\VCRUNTIME140.dll',
'BINARY'),
# 剩下的項就省略了
]
可以看到，a.binaries 是一個列表，其中的元素是元組，元組有3個內容：
- 依賴檔案目標路徑
- 依賴檔案原始路徑
- 檔案型別
我們只需要修改 a.binaries ，在目標路徑前加上 libs 就可以了，同時，要確保 python310.dll 和 base_library.zip 不被修改。
修改依賴目標位置
編輯 hello.spec 檔案：
# -*- mode: python ; coding: utf-8 -*-
block_cipher = None
a = Analysis(
['hello.py'],
pathex=[],
binaries=[],
datas=[],
hiddenimports=[],
hookspath=[],
hooksconfig={},
runtime_hooks=['hook.py'],
excludes=[],
win_no_prefer_redirects=False,
win_private_assemblies=False,
cipher=block_cipher,
noarchive=False,
)
import re
import os
# 用一個函數選擇性對依賴檔案目標路徑改名
def new_dest(package: str):
if package == 'base_library.zip' or re.match(r'python\d+.dll', package):
return package
return 'libs' + os.sep + package
a.binaries = [(new_dest(x[0]), x[1], x[2]) for x in a.binaries]
# 列印 a.binaries，檢查依賴檔案目標路徑
from pprint import pprint
pprint(a.binaries)
pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)
exe = EXE(
pyz,
a.scripts,
[],
exclude_binaries=True,
name='hello',
debug=False,
bootloader_ignore_signals=False,
strip=False,
upx=True,
console=True,
disable_windowed_traceback=False,
argv_emulation=False,
target_arch=None,
codesign_identity=None,
entitlements_file=None,
)
coll = COLLECT(
exe,
a.binaries,
a.zipfiles,
a.datas,
strip=False,
upx=True,
upx_exclude=[],
name='hello',
)
然後，用 pyinstaller hello.spec 進行打包，再執行得到的 hello.exe，得到如下輸出：
[('libs\\VCRUNTIME140.dll',
'C:\\Users\\Haujet\\AppData\\Local\\Programs\\Python\\Python310\\VCRUNTIME140.dll',
'BINARY'),
('python310.dll',
'C:\\Users\\Haujet\\AppData\\Local\\Programs\\Python\\Python310\\python310.dll',
'BINARY'),
('libs\\_decimal.pyd',
'C:\\Users\\Haujet\\AppData\\Local\\Programs\\Python\\Python310\\DLLs\\_decimal.pyd',
'EXTENSION'),
# 剩下的省略了
]
得到了乾淨的輸出目錄， hello.exe 也能夠正常執行：
但是如你所見，這個程式脾氣不好，爆粗口，使用者可能會想要修改其中的程式碼，但又不想設定環境、重新打包。
因此接下來我們就要把 hello.exe 作為程式入口，實際的邏輯寫在 hello_main.py ，同時確保 hello_main.py 中的依賴都被正確打包到 libs 資料夾。這樣，使用者就可以通過編輯 hello_main.py 來修改程式行為了。
第二步：打包可修改程式
製作入口
新建檔案 hello_main.py ，將 hello.py 的程式碼邏輯複製進去，並且要稍作修改：
# coding: utf-8
from rich import print
def main(*args, **kwargs):
print('[red]Hello mother fucker! ')
input('按下回車繼續')
if __name__ == "__main__":
main()
然後修改 hello.py，將其製作成程式入口，呼叫 hello_main.py 中的 main 函數：
# coding: utf-8
import hello_main
hello_main.main()
然後，用 pyinstaller hello.spec 進行打包，但是我們會發現，打包出的程式與之前一模一樣，雖然打包出的 hello.exe 能正常執行，但是我們卻找不到 hello_main.py ：
檢視被打包的 py 模組
找不到 hello_main.py 的原因是，它被打包進了 hello.exe 中，所有被參照到的 py 檔案都會被打包進 exe 檔案中。
我們回顧一下開頭 spec 檔案中內容的註釋：
# 除此之外，a 還有一些沒有列出的屬性：
# pure 是一個列表，包含了所有純 Python 模組的資訊，這些模組會被打包到一個 .pyz 檔案中。
# scripts 是一個列表，包含了你的 Python 指令碼的資訊。這些指令碼會被打包到一個 exe 檔案中。
hello.py 是主指令碼，會被加到 a.scripts 列表中，進而打包到 exe 中，hello_main.py 則是作為被匯入的 py 模組，被加到了 a.pure 列表，後序被打包到 pyz 中。我們可以編輯 hello.spec，在打包過程中顯示出有哪些 py 檔案被打包了：
a = Analysis(
['hello.py'],
pathex=[],
binaries=[],
datas=[],
hiddenimports=[],
hookspath=[],
hooksconfig={},
runtime_hooks=['hook.py'],
excludes=[],
win_no_prefer_redirects=False,
win_private_assemblies=False,
cipher=block_cipher,
noarchive=False,
)
import re
import os
# 用一個函數選擇性對依賴檔案目標路徑改名
def new_dest(package: str):
if package == 'base_library.zip' or re.match(r'python\d+.dll', package):
return package
return 'libs' + os.sep + package
a.binaries = [(new_dest(x[0]), x[1], x[2]) for x in a.binaries]
# 列印 a.pure，顯示哪些 py 檔案被打包
from pprint import pprint
pprint(a.pure)
pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)
... # 後面的程式碼省略了
然後，用 pyinstaller hello.spec 進行打包，在輸出中可以搜尋到：
[
...
('http.cookiejar', '...\\Python310\\lib\\http\\cookiejar.py', 'PYMODULE'),
('hello_main', 'D:\\PyInstaller優雅打包\\hello_main.py', 'PYMODULE'),
('rich', '...Python310\\lib\\site-packages\\rich\\__init__.py','PYMODULE'),
...
]
hello_main 赫然在列。
阻止 py 模組被打包
既然 hello_main.py 是因為被自動加入到 a.pure 列表導致被打包的，那我們就可以在 spec 檔案中將它從 a.pure 中剔除。
此外，我們還需要將 hello_main.py 新增到 a.datas 列表中，將它作為普通檔案被複制到打包資料夾，編輯 hello.spec ：
# -*- mode: python ; coding: utf-8 -*-
block_cipher = None
a = Analysis(
['hello.py'],
pathex=[],
binaries=[],
datas=[],
hiddenimports=[],
hookspath=[],
hooksconfig={},
runtime_hooks=['hook.py'],
excludes=[],
win_no_prefer_redirects=False,
win_private_assemblies=False,
cipher=block_cipher,
noarchive=False,
)
import re
import os
# 用一個函數選擇性對依賴檔案目標路徑改名，重定向到 libs 資料夾
def new_dest(package: str):
if package == 'base_library.zip' or re.match(r'python\d+.dll', package):
return package
return 'libs' + os.sep + package
a.binaries = [(new_dest(x[0]), x[1], x[2]) for x in a.binaries]
# 將需要排除的模組寫到一個列表（不帶 .py）
my_modules = ['hello_main', ]
# 將被排除的模組新增到 a.datas
for name in my_modules:
source_file = name + '.py'
dest_file = name + '.py'
a.datas.append((source_file, dest_file, 'DATA'))
# 篩選 a.pure
a.pure = [x for x in a.pure if x[0] not in my_modules]
# 列印 a.dates ，顯示哪些檔案被複制到打包資料夾
from pprint import pprint
pprint(a.datas)
pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)
exe = EXE(
pyz,
a.scripts,
[],
exclude_binaries=True,
name='hello',
debug=False,
bootloader_ignore_signals=False,
strip=False,
upx=True,
console=True,
disable_windowed_traceback=False,
argv_emulation=False,
target_arch=None,
codesign_identity=None,
entitlements_file=None,
)
coll = COLLECT(
exe,
a.binaries,
a.zipfiles,
a.datas,
strip=False,
upx=True,
upx_exclude=[],
name='hello',
)
此時，
hook.py中的
然後，用 pyinstaller hello.spec 進行打包，輸出中得到：
[
('base_library.zip', 'D:\\PyInstaller優雅打包\\build\\hello\\base_library.zip', 'DATA'),
('hello_main.py', 'hello_main.py', 'DATA')
]
同時也可以在打包輸出資料夾中看到 hello_main.py 了，並且程式能正常執行：
編輯 py 後再執行
現在，使用者就可以編輯 hello_main.py 後直接從 hello.exe 執行了，不需要重新打包（需要引入新庫的情況除外）。
使用者終於可以動手把這個脾氣暴躁的程式教育成一個健康積極的程式了：
後記
此外，還可以進一步修改 hello.spec ，進而得到更完善的程式，例如匯入額外的包、新增圖示、新增其他資源。
這就是一個打包程式的模板了。
多虧有 ChatGPT 這一個知識淵博、毫無厭倦的老師，耐心的回答我提出的每一個細節問題，才能有這麼一個完美的打包方案。
