安裝 Python 模組

電子郵件:

distutils-sig@python.org

作為一個普及的開源開發專案,Python 有一個活躍的支持社群,由其貢獻者及使用者組成,而他們也讓他們的軟體可被其他 Python 開發者在開源授權條款下使用。

這樣可以讓 Python 使用者們有效地共享和合作,並受益於其他人對常見(有時甚至是罕見)的問題已經建立的解決方案,更可以在公用社群中潛在地貢獻他們自己的解決方案。

這份指南涵蓋了上述過程中的安裝部分。如果是要建立及分享你自己的 Python 專案,請參考 Python packaging user guide

備註

對於企業和其他機構的使用者,要注意到,許多組織對於使用和貢獻開源軟體都有自己的政策。在開始使用配備 Python 的發布及安裝工具時,請將那些政策納入考量。

關鍵術語

  • pip 是首選的安裝程式。從 Python 3.4 開始,它被預設包含在 Python 二進制安裝程式中。

  • virtual environment(虛擬環境)是一種半隔離的 Python 環境,可以為某個特定應用程式安裝其所需的套件,而不用在整個系統上安裝它們。

  • venv 是建立虛擬環境的標準工具,它從 Python 3.3 開始成為 Python 的一部分。從 Python 3.4 開始,它會預設地安裝 pip 到所有被建立的虛擬環境。

  • virtualenvvenv 的一個第三方替代方案(及其前身)。它使虛擬環境可以在 Python 3.4 之前的版本被使用,那些版本要不是根本沒提供 venv,就是無法自動安裝 pip 到所建立的環境中。

  • Python 套件索引 (Python Package Index) 是開源授權套件的一個公共儲存庫,其中的套件皆可被其他 Python 使用者所使用。

  • Python 封裝管理站 (Python Packaging Authority) 是一個由開發者和說明文件作者組成的團隊,負責維護及改進標準封裝工具,以及相關的元資料 (metadata) 和檔案格式標準。他們在 GitHub 平台上維護各種工具、說明文件及問題追蹤系統。

  • distutils 是最早的建置和發布系統,於 1998 年首次被加入 Python 標準函式庫。雖然直接使用 distutils 的方式已經被逐步淘汰,它仍然是現今封裝和發布的基礎結構根基,而且它不僅仍然是標準函式庫的一部分,它的名稱也以其他的方式存活著(例如:用於協調 Python 封裝標準開發的郵寄清單就是以它命名)。

在 3.5 版的變更: 對於建立虛擬環境,現在推薦使用 venv

基本用法

標準封裝工具皆是以能從命令列使用的方式被設計的。

以下指令將從 Python 套件索引安裝一個模組的最新版本及其依賴套件 (dependencies):

python -m pip install SomePackage

備註

對於 POSIX 使用者(包括 macOS 和 Linux 使用者),本指南中的範例皆假設有使用 virtual environment

對於 Windows 使用者,本指南中的範例皆假設在安裝 Python 時,「可調整系統 PATH 環境變數」的選項已被選取。

在命令列中直接指定一個明確的或最小的版本也是可行的。當使用像是 >< 的比較運算子,或某些可被 shell 所解釋的其他特殊字元時,套件名稱與版本編號應該要放在雙引號內:

python -m pip install SomePackage==1.0.4    # specific version
python -m pip install "SomePackage>=1.0.4"  # minimum version

通常,如果一個合適的模組已被安裝,嘗試再次安裝它將不會有任何效果。要升級現有的模組就必須明確地請求:

python -m pip install --upgrade SomePackage

關於 pip 及其能力的更多資訊和資源,可以在 Python 封裝使用者指南中找到。

虛擬環境的建立是使用 venv 模組來完成。要在一個已啟用的虛擬環境中安裝套件,可使用前面展示的指令。

我該如何...?

接下來是關於一些常見任務的快速解答或連結。

...在 Python 3.4 之前的 Python 版本中安裝 pip

Python 是從 Python 3.4 才開始綁定 pip 的。對於更早的版本,pip 需要被「自助安裝 (bootstrapped)」,請參考 Python 封裝使用者指南中的說明。

...只為目前的使用者安裝套件?

--user 選項傳給 python -m pip install,這樣將會只為目前使用者而非系統的所有使用者安裝套件。

...安裝科學的 Python 套件?

許多科學類 Python 套件都有複雜的二進制依賴套件,且目前不太容易直接使用 pip 安裝。目前為止,使用其他方法而非嘗試用 pip 來安裝它們,對使用者來說通常會更簡單。

...平行安裝多個 Python 版本並使用它們?

在 Linux、macOS 以及其他 POSIX 系統中,使用帶有版本編號的 Python 指令並結合 -m 開關參數 (switch),來運行 pip 的適當副本:

python2   -m pip install SomePackage  # default Python 2
python2.7 -m pip install SomePackage  # specifically Python 2.7
python3   -m pip install SomePackage  # default Python 3
python3.4 -m pip install SomePackage  # specifically Python 3.4

使用帶有合適版本編號的 pip 指令,也是可行的。

在 Windows 中,使用 Python 啟動指令 py 並結合 -m 開關參數 (switch):

py -2   -m pip install SomePackage  # default Python 2
py -2.7 -m pip install SomePackage  # specifically Python 2.7
py -3   -m pip install SomePackage  # default Python 3
py -3.4 -m pip install SomePackage  # specifically Python 3.4

常見的安裝問題

在 Linux 上安裝套件至系統 Python

在 Linux 系統,Python 的某個安裝版本通常會被內含在 Linux 的發行版中。要安裝套件到這個 Python 版本上需要系統的 root 權限,並且可能會干擾到系統套件管理器的運作。如果其他系統組件非預期地以 pip 被升級,也會干擾這些組件的運作。

在這樣的系統上,以 pip 安裝套件時,通常較好的方式是使用虛擬環境,或以個別使用者安裝。

未安裝 pip

pip 沒有預設被安裝也是有可能的。一個潛在的解法是:

python -m ensurepip --default-pip

這裡還有其他關於安裝 pip的資源。

安裝二進制擴充 (binary extension)

Python 基本上相當倚賴以原始碼為基礎的發布方式,也會期望使用者在安裝過程的某個階段,從原始碼來編譯擴充模組。

隨著引入對二進制 wheel 格式的支援,以及透過 Python 套件索引能夠至少在 Windows 和 macOS 發布 wheel 檔案,這個問題預期將會逐漸消失,因為使用者將能夠更頻繁地安裝預建置 (pre-built) 的擴充,而不再需要自己建置它們。

有一些解決方案,可用來安裝那些還無法以預建置的 wheel 檔案被使用的科學軟體,這些方案也有助於取得其他的二進制擴充,且無需在本機對它們進行建置。