Python 開發者的「可編輯模式」神技 - pip install -e

Posted on
詳解 Python 開發者的核心利器 —— 可編輯模式 (`pip install -e`)。本文解釋其如何透過符號連結讓原始碼修改立即生效，免去反覆安裝的煩惱，並分享在模組化開發與內部套件維護時的最佳實務。

在開發 Python 套件時，你是否曾經因為改了一行程式碼，就得重新跑一次 pip install . 才能看到效果？這種「改一行、裝一次」的迴圈，在開發初期可能還能忍受，但當你的套件越來越大、測試越來越頻繁時，它就會變成一場噩夢。

pip install -e（可編輯模式）就是為了終結這個痛苦而生的。

什麼是可編輯模式 (Editable Mode)？

在標準安裝 (pip install .) 中，Python 會將套件檔案複製到虛擬環境的 site-packages 目錄下。如果你修改了原始碼，必須重新安裝才能看到變化。

使用 -e 選項時：

  • 連結而非複製： pip 只會在 site-packages 中建立一個指向原始路徑的指標（通常是 .pth 檔案或現代的啟動機制）。
  • 即時同步： 只要你存檔，執行中的程式或測試就會直接讀取到最新的程式碼。

簡單來說，它在你的開發目錄和 Python 環境之間建立了一條「即時通道」。

為什麼需要使用它？

  • 套件開發： 當你正在開發一個預計要發佈到 PyPI 的套件時，這幾乎是標準配備。
  • 專案解耦： 將大型專案拆分為多個本地模組，並透過 pip 進行管理，同時保持開發的靈活性。
  • 貢獻開源專案： 修正他人套件的 Bug 時，可以先 clone 下來並以 -e 安裝，方便邊改邊測。

背後原理簡述

在執行 pip install -e . 後，pip 會：

  1. 讀取 pyproject.toml 或 setup.py。
  2. 在 site-packages 目錄下產生一個連結檔案。
  3. 當 Python 解析 import 時，會根據該連結直接跳轉到你的開發路徑讀取檔案。

這就像是在圖書館的書架上放了一張「請到 X 教室找這本書」的紙條，而不是真的把書搬過來。

誰可以用？

只要一個專案具備標準的套件設定檔（pyproject.toml 或 setup.py），就能使用可編輯模式。換句話說，凡是能被打包上傳到 PyPI 的套件，都能享受這個魔法。

不管是你自己的私人專案、公司內部的共用 Library、還是從 GitHub clone 下來的開源套件，只要根目錄有這些設定檔，pip install -e . 就能直接運作。

實戰範例

假設你有以下專案結構：

1
2
3
4
5
my_awesome_pkg/
├── pyproject.toml
└── src/
    └── my_pkg/
        └── __init__.py

其中 pyproject.toml 只需要最基本的設定：

1
2
3
4
5
6
7
[build-system]
requires = ["setuptools>=64"]
build-backend = "setuptools.backends._legacy:_Backend"

[project]
name = "my-pkg"
version = "0.1.0"

安裝方式非常簡單：

1
2
3
4
5
# 進入專案根目錄
cd my_awesome_pkg

# 使用可編輯模式安裝目前目錄
pip install -e .

此時，若你在 __init__.py 中新增一個函式，任何引用該套件的 Python 腳本都能立刻呼叫該函式，完全不需要重新執行 pip install。

進階建議與注意事項

  • 搭配虛擬環境： 強烈建議始終在 venv 或 conda 環境中使用，避免污染系統全域路徑。
  • 檔案異動限制： 雖然「內容」修改會立即生效，但如果你新增了進入點 (entry_points)（例如新的 CLI 工具名稱），則通常需要重新執行一次 pip install -e .。
  • 清理建議： 若要解除連結，使用 pip uninstall <package_name> 即可，它會同時刪除連結檔案。

結語

pip install -e <path> 是所有進階 Python 開發者的標準工作流，它消除了「開發」與「安裝」之間的繁瑣同步過程。如果你正在開發自己的 Library 或處理複雜的專案結構，絕對不要忽視這個強大功能。

也許你也會想看看