辛辛苦苦寫好的 Python 腳本，發(fā)給同事卻要讓他裝環(huán)境？用 PyInstaller 打包成單個 exe 文件，雙擊就能運行，省心又專業(yè)。本文從零開始，手把手教你用 PyInstaller 打包 Python 程序，解決新手常遇到的坑。

一、為什么需要 PyInstaller？

寫了個自動化腳本，發(fā)給同事，他說“Python 是啥？怎么運行？” 如果你不想讓每個人都安裝 Python 和依賴包，PyInstaller 就是救星。

PyInstaller 的作用：把 Python 腳本及其依賴打包成一個獨立的可執(zhí)行文件（Windows 下是 .exe），用戶無需 Python 環(huán)境，雙擊即可運行。

支持平臺：Windows、macOS、Linux。

二、安裝 PyInstaller

最簡單的方式是用 pip 安裝：pip install pyinstaller

如果下載慢，可以換國內(nèi)源：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple pyinstaller

安裝完成后，在命令行輸入以下命令確認是否成功：pyinstaller --version

正常會顯示版本號，如 6.7.0。

三、快速上手：打包一個最簡單的腳本

假設(shè)我們有一個名為 hello.py 的腳本，內(nèi)容如下：

print("Hello, PyInstaller!")
input("按回車鍵退出...")

進入腳本所在目錄，打開命令行，執(zhí)行：

pyinstaller hello.py

命令執(zhí)行后，會生成兩個目錄：

• build：臨時文件目錄（可忽略）
• dist：打包好的可執(zhí)行文件就在這里

在 dist/hello 目錄下（Windows 為 dist/hello）找到 hello.exe（或 hello），雙擊運行，就能看到輸出結(jié)果。

注意：默認生成的是一個文件夾，里面包含 exe 和一堆依賴文件。如果想生成單個 exe 文件，加上 -F 參數(shù)：

pyinstaller -F hello.py

此時 dist 目錄下只有一個 hello.exe，雙擊就能運行。

四、常用參數(shù)詳解

-F, --onefile：打包成單個 exe 文件

-D, --onedir：打包成一個文件夾（默認）

-w, --windowed：不顯示控制臺窗口（適用于 GUI 程序）

-i, --icon：指定 exe 的圖標（如 -i icon.ico）

--name：指定生成的 exe 文件名

--add-data：添加額外數(shù)據(jù)文件（如圖片、配置文件）

--hidden-import：手動導(dǎo)入 PyInstaller 未能自動發(fā)現(xiàn)的模塊

五、實戰(zhàn)：打包帶依賴和 GUI 的程序

假設(shè)我們有一個簡單的 GUI 程序 gui_app.py，用 tkinter 做了一個小窗口，還依賴一個外部的 config.json 文件。

import tkinter as tk
import json

with open("config.json", "r", encoding="utf-8") as f:
    config = json.load(f)

root = tk.Tk()
root.title(config.get("title", "My App"))
label = tk.Label(root, text=config.get("text", "Hello"))
label.pack()
root.mainloop()

config.json內(nèi)容：

{
    "title": "我的應(yīng)用",
    "text": "歡迎使用 PyInstaller"
}

1. 打包單個 exe，不顯示控制臺窗口

pyinstaller -F -w --add-data "config.json;." gui_app.py

解釋：

• -F：單文件
• -w：無控制臺窗口
• --add-data "config.json;."：將 config.json 文件添加到打包中，并放在 exe 同目錄（; 是 Windows 下的分隔符，Linux/macOS 用 :）

2. 解決路徑問題

程序里如果使用相對路徑讀取配置文件，打包后可能會找不到。推薦在代碼中自動獲取正確的路徑：

import sys
import os

def resource_path(relative_path):
    """獲取資源的絕對路徑，適配 PyInstaller 打包"""
    try:
        base_path = sys._MEIPASS  # PyInstaller 臨時解壓目錄
    except AttributeError:
        base_path = os.path.abspath(".")
    return os.path.join(base_path, relative_path)

# 使用
config_path = resource_path("config.json")
with open(config_path, "r") as f:
    config = json.load(f)

然后在打包時，添加 --add-data 并告知 PyInstaller 將文件放到 _MEIPASS 目錄下。

pyinstaller -F -w --add-data "config.json;." gui_app.py

這樣即使打包成單個 exe，程序也能正確讀取到配置文件。

六、常見問題與解決方案

1. 打包后運行報錯：ModuleNotFoundError: No module named 'xxx'

原因：PyInstaller 沒有自動識別到某些依賴模塊。

解決：使用 --hidden-import 手動指定。

pyinstaller -F --hidden-import=pandas --hidden-import=openpyxl my_script.py

2. 打包文件太大，怎么辦？

使用 --exclude-module 排除不需要的模塊（如 matplotlib、numpy 很占體積）。

如果用了虛擬環(huán)境，在干凈的環(huán)境中打包，避免打包多余包。

3. 圖標不生效

確保圖標是 .ico 格式（Windows 下），其他格式可能不識別。打包時：

pyinstaller -F -i myicon.ico my_script.py

4. 打包后雙擊閃退

閃退通常是因為程序報錯后立即退出。可以在代碼開頭加 try...except 捕獲錯誤并暫停：

try:
    # 你的代碼
except Exception as e:
    print("Error:", e)
    input("按回車鍵退出...")

這樣就能看到錯誤信息，方便排查。

七、進階：使用 spec 文件自定義打包

當參數(shù)很多時，可以生成 .spec 配置文件，然后通過 pyinstaller xxx.spec 打包，方便修改和復(fù)用。

生成 spec 文件：

pyinstaller hello.py # 會生成 hello.spec

編輯 hello.spec，修改 a.datas 添加數(shù)據(jù)文件，修改 exe 設(shè)置圖標等。然后執(zhí)行：

pyinstaller hello.spec

八、總結(jié)

最佳實踐：

• 在虛擬環(huán)境中打包，減少體積。
• 使用 -F 生成單文件，便于分發(fā)。
• 使用 resource_path 函數(shù)處理文件路徑。
• 遇到閃退時，先用控制臺版本（不加 -w）調(diào)試。
• 對于大型項目，用 spec 文件管理配置。

現(xiàn)在，你可以把自己的 Python 腳本打包成 exe 發(fā)給任何人，再也不用擔(dān)心環(huán)境問題了?？烊ピ囋嚢桑?/p>

到此這篇關(guān)于使用PyInstaller將Python腳本打包成exe的新手入門指南的文章就介紹到這了,更多相關(guān)PyInstaller打包Python腳本內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評論