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

一、為什么需要 PyInstaller？

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

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

支持平臺(tái)：Windows、macOS、Linux。

二、安裝 PyInstaller

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

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

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

正常會(huì)顯示版本號(hào)，如 6.7.0。

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

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

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

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

pyinstaller hello.py

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

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

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

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

pyinstaller -F hello.py

此時(shí) dist 目錄下只有一個(gè) hello.exe，雙擊就能運(yùn)行。

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

-F, --onefile：打包成單個(gè) exe 文件

-D, --onedir：打包成一個(gè)文件夾（默認(rèn)）

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

-i, --icon：指定 exe 的圖標(biāo)（如 -i icon.ico）

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

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

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

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

假設(shè)我們有一個(gè)簡單的 GUI 程序 gui_app.py，用 tkinter 做了一個(gè)小窗口，還依賴一個(gè)外部的 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. 打包單個(gè) exe，不顯示控制臺(tái)窗口

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

解釋：

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

2. 解決路徑問題

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

import sys
import os

def resource_path(relative_path):
    """獲取資源的絕對(duì)路徑，適配 PyInstaller 打包"""
    try:
        base_path = sys._MEIPASS  # PyInstaller 臨時(shí)解壓目錄
    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)

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

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

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

六、常見問題與解決方案

1. 打包后運(yùn)行報(bào)錯(cuò)：ModuleNotFoundError: No module named 'xxx'

原因：PyInstaller 沒有自動(dòng)識(shí)別到某些依賴模塊。

解決：使用 --hidden-import 手動(dòng)指定。

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

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

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

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

3. 圖標(biāo)不生效

確保圖標(biāo)是 .ico 格式（Windows 下），其他格式可能不識(shí)別。打包時(shí)：

pyinstaller -F -i myicon.ico my_script.py

4. 打包后雙擊閃退

閃退通常是因?yàn)槌绦驁?bào)錯(cuò)后立即退出?？梢栽诖a開頭加 try...except 捕獲錯(cuò)誤并暫停：

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

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

七、進(jìn)階：使用 spec 文件自定義打包

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

生成 spec 文件：

pyinstaller hello.py # 會(huì)生成 hello.spec

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

pyinstaller hello.spec

八、總結(jié)

最佳實(shí)踐：

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

現(xiàn)在，你可以把自己的 Python 腳本打包成 exe 發(fā)給任何人，再也不用擔(dān)心環(huán)境問題了。快去試試吧！

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

最新評(píng)論