安裝 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" 到所有被建立的虛擬
  環境。

* "virtualenv" 是 "venv" 的一個第三方替代方案（及其前身）。它使虛擬環
  境可以在 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 封裝使用者指南：建立和使用虛擬環境


基本用法
========

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

以下指令將從 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 封裝使用者指南：安裝 Python 發布套件


我該如何...？
=============

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


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

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

也參考: Python 封裝使用者指南：安裝套件的需求


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

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


...安裝科學的 Python 套件？
---------------------------

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

也參考: Python 封裝使用者指南：安裝科學套件


...平行安裝多個 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" 檔案被使用的科
學軟體，這些方案也有助於取得其他的二進制擴充，且無需在本機對它們進行建
置。

也參考: Python 封裝使用者指南：二進制擴充
