這 篇文章將為您揭開 Python 套件命名潛規則的神秘面紗，
整理出最常見的「表裡不一」名單，助您避開開發路上的隱形坑。
—
## 1. 核心觀念：包裹 (Package) vs. 模組 (Module)
要理解這個現象，首先要區分兩個層次：
* **PyPI 註冊名稱 (Distribution Package Name)**
* 這是給 **`pip`** 看的。
* 就像商品的「上架條碼」或「完整商品名」。
* 為了避免重複，名稱必須全球唯一，且不能與現有的衝突。
* 例如：`python-docx`, `beautifulsoup4`, `opencv-python`。
* **程式導入名稱 (Import Package/Module Name)**
* 這是給 **Python 直譯器** (`import` 指令) 看的。
* 就像商品的「小名」或「內容物」。
* 為了寫程式方便，通常越短越好，或者沿用該領域的慣例。
* 例如：`docx`, `bs4`, `cv2`。
**重點：** 這兩個名稱是由套件作者自行定義的，
**並沒有強制規定必須相同**。
—
## 2. 常見的「表裡不一」對照表
這是開發者最容易踩到的雷區，建議直接存下來備查：
## 3. 為什麼會這樣？背後的三大原因
### 原因一：歷史包袱與名稱佔用 (Namespace Squatting)
這是最常見的原因。
* **案例**：`python-docx`
* **故事**：早在多年前，已經有人註冊了 `docx` 這個名字，但功能很陽春且早已停止維護。後來的新作者開發了功能強大的新版，但因為 `docx` 這個名字被佔用了，只好改名為 `python-docx` 上架。但為了讓大家寫程式時直覺（畢竟是在處理 docx），程式碼裡還是保留 `import docx` 的寫法。
### 原因二：C/C++ 函式庫的綁定 (Bindings)
許多 Python 套件其實是 C 或 C++ 強大函式庫的「外殼」。
* **案例**：`opencv-python` -> `import cv2`
* **故事**：OpenCV 是 C++ 寫的。Python 版本只是它的介面 (Wrapper)。安裝包名稱通常會帶有 `-python` 後綴以示區別，但 Import 時為了致敬 OpenCV 的經典版本 (v2.x)，傳統上習慣使用 `cv2`。
### 原因三：捷徑包與過路站 (Dummy Packages)
* **案例**：`bs4` vs `beautifulsoup4`
* **真相**：你確實可以 `pip install bs4`，而且通常也能跑。但 `bs4` 往往只是一個「空殼」，它的唯一作用就是告訴 pip：「去幫我下載 `beautifulsoup4`」。
* **風險**：這類非官方的空殼包可能由不同人維護，一旦停止更新，可能會讓你裝不到最新版的核心套件，甚至有安全疑慮。**建議還是使用官方正名的 `beautifulsoup4`。**
—
## 4. 如何確認我裝了什麼？
當你不確定自己電腦裡的 `import docx` 到底是裝了正確的 `python-docx` 還是錯誤的舊版時，可以用以下幾招「照妖鏡」：
### 第一招：pip show (查身分證)
在終端機輸入：
pip show python-docx如果顯示資訊，代表你裝對了。如果是 `WARNING: Package(s) not found`，那可能就不妙了。
### 第二招：程式內檢查 (查內容物)
直接進入 Python 或在程式中執行：
import docx
print(docx.__file__) # 確認檔案位置
print(docx.__version__) # 正確版通常會顯示版本 (如 1.2.0)
# 錯誤版(舊版)通常會報錯說沒有 __version__## 總結
下次遇到 `ModuleNotFoundError` 或者 `ImportError` 時，先別急著懷疑人生。回頭檢查一下，是否又遇上了這些「名稱不一致」的調皮套件。
**記住口訣：**
> 裝 Word 用 **python-docx**，叫它 **docx**。
> 裝 CV 用 **opencv-python**，叫它 **cv2**。
> 裝 ML 用 **scikit-learn**，叫它 **sklearn**。
> 裝 圖形 用 **Pillow**，叫它 **PIL**。
( **註**：`PIL` 全大寫是為了相容 1995 年的舊版慣例，雖然違背現代的小寫規範，但必須照著寫。)
歷史背景：
原始的 PIL (Python Imaging Library) 誕生於 1995 年，那時候 Python 的社群規範 (PEP 8) 還沒有完全確立或是大家沒那麼嚴格遵守。那時的風格傾向於「縮寫全大寫」或是「CamelCase」。
當時的作者選擇了 PIL 作為頂層套件名稱。
Pillow 的承接：
當 Pillow 接手維護 PIL 後，為了保持對舊有程式碼的 100% 相容性 (Backward Compatibility)，他們必須保留 import PIL 這個入口。
如果不這樣做，全世界成千上萬依賴 import PIL.Image 的舊專案都會瞬間壞掉。
現代建議：
雖然 import PIL 看起來違背了全小寫的慣例，但在這個特定套件上，它就是標準寫法。
推薦hahow線上學習python: https://igrape.net/30afN