如何安裝 Python .whl 檔案

若要安裝 Python .whl 檔案，請先選擇與 Python 直譯器及平台相容的 wheel，再於終端機執行 python -m pip install "/path/to/package.whl"。套件會安裝到該 python 指令所屬的環境。Wheel 是可直接安裝的套件發行格式，通常應使用 pip 安裝，而不是自行解壓縮。

認識 .whl 檔案

Wheel 是 Python 套件的建置發行格式，採用 ZIP 封存檔，並以安裝工具可辨識的配置收納套件檔案與中繼資料。Wheel 可以包含 Python 程式碼、已編譯的擴充模組，或兩者兼有。安裝相容的 wheel 通常可省去在本機從原始碼建置套件的步驟。

檔名會標示發行套件、版本與相容性標籤，後面再接上 .whl 副檔名。這些標籤會描述 Python 實作與版本、應用程式二進位介面（ABI），以及作業系統或處理器平台等資訊。標記為 py3-none-any 的 wheel 通常適用於 Python 3，且不含平台專屬的二進位元件；其他 wheel 則可能僅適用於特定 Python 組建或系統。

選擇相容的 Wheel

請從套件發行者或你信任的套件索引取得檔案。下載前，先查看套件的安裝說明，並選擇標籤符合預定安裝環境中 Python 直譯器與電腦的 wheel。即使套件名稱正確，若檔案是為其他作業系統、處理器架構或 Python ABI 建置，也可能無法使用。

若要確認指令會使用哪個直譯器，請執行 python --version 和 python -m pip --version。如果系統使用 python3 作為 Python 3 指令，請一致地使用 python3。若電腦上有多個 Python 安裝版本或虛擬環境，請先啟用預定使用的環境，或直接使用該環境的直譯器路徑。這樣可避免把套件安裝到一個環境，之後卻從另一個環境嘗試匯入。

當目標電腦無法上網或網路受限時，本機 wheel 就很實用。你可以在可連線的電腦上下載 wheel 及其所需的相依套件 wheel，再將檔案傳到目標電腦，並從本機檔案安裝。--no-index 和 --find-links 選項可讓 pip 到本機目錄尋找相依套件，但不會自動提供缺少的相依套件。

使用 pip 安裝 .whl 檔案

使用 python -m pip，可確保 pip 在 python 指定的直譯器下執行。請將範例路徑替換為 wheel 的位置與檔名：

from pathlib import Path
import csv
import hashlib
import subprocess
import sys
import tempfile
import zipfile

with tempfile.TemporaryDirectory() as directory:
    root = Path(directory)
    wheel = root / "sample_wheel_demo-1.0-py3-none-any.whl"
    dist_info = "sample_wheel_demo-1.0.dist-info"

    files = {
        "sample_wheel_demo.py": "message = 'wheel installed'\n",
        f"{dist_info}/METADATA": (
            "Metadata-Version: 2.1\n"
            "Name: sample-wheel-demo\n"
            "Version: 1.0\n\n"
        ),
        f"{dist_info}/WHEEL": (
            "Wheel-Version: 1.0\n"
            "Generator: example\n"
            "Root-Is-Purelib: true\n"
            "Tag: py3-none-any\n"
        ),
    }
    record_path = f"{dist_info}/RECORD"
    with zipfile.ZipFile(wheel, "w") as archive:
        for name, contents in files.items():
            archive.writestr(name, contents)
        rows = []
        for name, contents in files.items():
            digest = hashlib.sha256(contents.encode()).digest()
            import base64
            encoded = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
            rows.append((name, f"sha256={encoded}", str(len(contents.encode()))))
        rows.append((record_path, "", ""))
        import io
        record = io.StringIO()
        csv.writer(record, lineterminator="\n").writerows(rows)
        archive.writestr(record_path, record.getvalue())

    target = root / "installed"
    result = subprocess.run(
        [sys.executable, "-m", "pip", "install", "--no-index", "--no-deps",
         "--target", str(target), str(wheel)],
        capture_output=True, text=True,
    )
    if result.returncode == 0:
        print("Installed sample-wheel-demo 1.0")
    else:
        print("Installation failed:", result.stderr.strip())
        raise SystemExit(result.returncode)

這個獨立範例會在暫存目錄中建立一個小型 wheel，並要求目前直譯器的 pip 將它安裝到另一個目標目錄。若要安裝現有的 wheel，指令格式如下：python -m pip install "/path/to/package.whl"。將路徑加上引號可處理目錄或檔名含空格的情況。在 Windows 上，可使用類似 "C:\Users\Ada\Downloads\package.whl" 的路徑；在 PowerShell 或命令提示字元中，也可使用相同的引號格式。範例中顯示的訊息文字維持英文，程式碼區塊會原樣保留。

如果你已下載 wheel 及其相依套件以供離線安裝，請讓 pip 搜尋它們所在的目錄：python -m pip install --no-index --find-links "/path/to/wheels" "/path/to/package.whl"。若本機沒有這些相依套件檔案，pip 在離線時就無法下載它們。

排解安裝錯誤

• **找不到相符的發行版本或 wheel 標籤不受支援：**確認 wheel 的 Python、ABI 與平台標籤符合直譯器和電腦。請從發行者下載相符的組建，或依照其說明改用其他受支援的安裝方式。
• **缺少相依套件：**閱讀 pip 的錯誤訊息，確認缺少哪個相依套件。請一併安裝相容的相依套件 wheel；若可連線，則可讓 pip 從已設定的套件索引解析相依套件。離線安裝時，請將所有必要的相依套件 wheel 放在本機目錄中。
• **套件已安裝，但無法匯入：**比較 python -m pip --version 顯示的直譯器與執行應用程式時使用的直譯器。請透過同一個直譯器執行兩者，或在安裝前啟用正確的虛擬環境。
• **權限遭拒：**建議使用由自己管理的虛擬環境。對系統直譯器而言，使用者層級安裝 python -m pip install --user ... 可能適用，但有些受管理環境會停用此功能；遇到這種情況時，請遵循環境管理員的指示。
• **找不到 pip 指令：**使用 python -m pip 或 python3 -m pip 呼叫 pip。如果回報 pip 無法使用，請依照該直譯器所屬 Python 發行版提供的 pip 設定說明操作。
• **Git 儲存庫中有 wheel：**複製儲存庫只會下載其中受追蹤的檔案；這不會安裝套件，也不保證儲存庫內有相容的 wheel。請依照專案維護者的說明操作、尋找已發佈的 wheel 資產，再使用 pip 安裝該本機檔案。請按照來源的信任與驗證做法處理儲存庫程式碼和下載的成品。

遇到任何錯誤時，請閱讀完整的 pip 訊息，判斷問題出在所選的 wheel、相依套件、Python 環境或權限。排除原因後，再使用預定的直譯器重新安裝。