SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

Ubuntu Python pip install 失敗:venv, pipx, uv 選擇指南

在 Ubuntu 伺服器執行 pip install 遇到 externally-managed-environment 錯誤?本文說明如何根據應用需求選擇 venv、pipx 或 uv,並正確設定 systemd 服務以避開系統限制。

為什麼在全新的 Ubuntu 伺服器上執行 pip install 會失敗

在伺服器上選擇 Python venv、pipx 或 uv,取決於你要安裝的內容。應用程式相依套件應放在應用程式目錄內的虛擬環境中。需要直接輸入名稱執行的命令列工具,應放在 pipx 中。uv 同時支援這兩種用途,並額外提供 lockfile;當第二台機器也必須建置相同環境時,這項功能就很重要。這些工具都不會安裝到系統 Python,因為新版 Ubuntu 伺服器會直接拒絕這項操作。

在 Ubuntu 24.04 上執行 sudo pip install requests 時,pip 會在下載任何檔案前停止。

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this behaviour by passing --break-system-packages.

這是 PEP 668(Python enhancement proposal 668,「externally managed environments」)的正常作用。Debian 與 Ubuntu 會在 /usr/lib/python3.12/EXTERNALLY-MANAGED 的直譯器旁放置標記檔案,而 pip 拒絕寫入任何帶有該檔案的直譯器。

這項規則存在,是因為 sys.path 的順序會造成問題。apt 會將函式庫安裝到 /usr/lib/python3/dist-packages。以 root 身分對系統直譯器執行 pip 時,pip 會寫入 /usr/local/lib/python3.12/dist-packages,而 Debian 的套件系統會將該目錄排在模組搜尋路徑的前面。使用 python3 -c 'import sys; print(sys.path)' 即可自行列出並查看順序。因此,pip 寫入的副本會遮蔽 apt 安裝的副本,影響系統上所有使用 /usr/bin/python3 執行的程式,包括發行版本身的工具。cloud-init 會從該直譯器匯入 requests、jinja2 和 PyYAML。若使用 pip 升級其中一個套件,結果安裝了不相容的版本,下一次開機時,某個你從未修改過的元件就可能失敗,並顯示指向某個你不知道位於相依鏈中的套件之 traceback。apt 仍會將自己的版本記錄為已安裝,因此不會發出警告。修復方式是使用 sudo pip uninstall --break-system-packages requests 移除 pip 安裝的副本,因為單獨執行 sudo apt reinstall python3-requests 只會改寫原本就被遮蔽的 apt 副本。

應遵循的規則很簡單。系統 Python 屬於發行版。不要安裝到其中,不要使用 pip 升級其中的函式庫,也不要刪除 EXTERNALLY-MANAGED 檔案來消除錯誤訊息。應交給 /usr/bin/python3 的唯一工作,是建立虛擬環境。

venv、pipx 與 uv:決策準則

請根據您要安裝的內容進行選擇,而非根據最近讀到的工具來決定。

  • 若為部署並以服務形式執行的應用程式(例如 Django 或 Flask 專案):請在該應用程式目錄內使用一個虛擬環境 (venv)。
  • 若為您希望在 PATH 上使用的命令列工具(例如 ansible 或 httpie):請使用 pipx,它會為每個工具提供獨立的環境,並在 PATH 上建立一個連結。
  • 若為需要鎖定檔 (lockfile)、更快速安裝,或發行版未提供之特定 Python 版本的專案:請使用 uv,它會產生一個標準的 venv 以及一個 uv.lock 檔案。
  • 若為發行版工具而非您的程式碼所需要的函式庫:請使用 sudo apt install python3-<name>,這是將任何內容加入系統直譯器 (system interpreter) 的唯一受支援方式。

pipx 與 uv tool install 的功能相同,因此若系統已安裝 uv,則無需額外安裝 pipx。您選擇的網頁框架對此並無影響:VPS 上的 Django 與 Flask 的差異在於 requirements.txt 內的內容,而非建構環境的方式。以下所有內容均使用 Ubuntu 24.04 及其內建的 Python 3.12,若您的版本不同,請自行調整路徑中的版本號。

建立每個應用程式的 venv

Ubuntu 會將 venv 模組從基礎 Python 套件中拆出。因此在精簡映像檔上,第一次嘗試會失敗,並明確指出缺少的項目。

The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt install python3.12-venv

先安裝該模組,再以將擁有程式碼的使用者建立環境。

sudo apt update
sudo apt install -y python3-venv
sudo install -d -o deploy -g deploy -m 755 /srv/myapp
sudo -u deploy python3 -m venv /srv/myapp/.venv
sudo -u deploy /srv/myapp/.venv/bin/pip install -r /srv/myapp/requirements.txt

請注意其中沒有的內容:沒有 source,也沒有 activate。/srv/myapp/.venv/bin/pip 會安裝到該環境中,是因為二進位檔所在的位置,而不是因為你在 shell 中匯出的任何內容。繼續之前,先確認這一點。

/srv/myapp/.venv/bin/python -c 'import sys; print(sys.prefix)'

這會輸出 /srv/myapp/.venv。如果輸出的是 /usr,表示你正在使用系統直譯器,套件也會被安裝到非預期的位置。

venv 的兩項特性會決定之後可以如何使用它。venv 不可搬移,因為 bin/ 中的每個 entry-point 指令碼都包含絕對 shebang 行:head -1 /srv/myapp/.venv/bin/pip 會讀取 #!/srv/myapp/.venv/bin/python。重新命名上層目錄後,這些指令碼會因 bad interpreter: No such file or directory 而失敗。venv 也會固定建立它的直譯器,該資訊會記錄在 /srv/myapp/.venv/pyvenv.cfg 的 home 行中,而 bin/python3 是指向 /usr/bin/python3 的符號連結。升級 release,使該路徑現在指向較新的 Python 後,新直譯器會在 lib/python3.13 目錄中尋找套件,但 venv 沒有該目錄,因此服務會在啟動時因 ModuleNotFoundError 而終止。這兩種情況的修正方式相同:刪除 venv,並從 requirements.txt 建立新的 venv。重新建立只需幾秒。絕對不要在不同機器之間複製 venv。

虛擬環境的存放位置與擁有權

請將虛擬環境放置於 /srv/myapp/.venv 的程式碼旁,並確保每個應用程式各自擁有獨立的 venv。如此一來,部署作業將集中於單一目錄,systemd 單元也能使用固定的路徑,且兩個應用程式不會因共用相依套件升級而互相干擾。請勿將 venv 放置於網頁伺服器直接對外公開的目錄中,因為該目錄包含您的相依套件,且通常也包含設定檔。

擁有權的設定值得花點時間規劃。請讓 deploy 使用者擁有程式碼與環境,並僅賦予服務帳號讀取與執行的權限。

sudo adduser --system --group --no-create-home myapp
sudo chown -R deploy:myapp /srv/myapp
sudo chmod -R o-rwx /srv/myapp

現在該服務可以匯入其相依套件,但無法對其進行修改。這意味著若網頁應用程式出現程式碼執行漏洞,攻擊者也無法悄悄替換磁碟上的函式庫,並在重啟後持續存在。關於此原則在系統其餘部分的應用,請參閱 以最小權限使用者執行服務。

命令列工具的 pipx

pipx 安裝的是應用程式,不是函式庫。每個工具都會在 ~/.local/share/pipx/venvs/<name> 下使用獨立環境,該工具的可執行檔則會連結至 ~/.local/bin,因此需要同一函式庫不同版本的兩個工具不會互相衝突。

sudo apt update
sudo apt install -y pipx
pipx ensurepath
pipx install httpie

pipx ensurepath 會透過編輯 shell 啟動檔案,將 ~/.local/bin 加入 PATH。它無法變更目前已進入的 shell,因此安裝後立即執行 http: command not found 通常表示您尚未登出再重新登入。Ubuntu 預設的 ~/.profile 只有在登入時該目錄已存在,才會加入 ~/.local/bin。因此這個問題只會在新帳號上首次發生,之後不會再出現。

如果將函式庫指定給 pipx,它會拒絕,並顯示以以下內容開頭的訊息:

No apps associated with package requests.

這表示您使用了錯誤的工具。函式庫應安裝在應用程式的 venv 中。

在伺服器上,位置是關鍵。單純執行 pipx install 會將所有內容放在單一使用者的家目錄下。以 myapp 執行的 systemd 單元無法看見它,root 的 cron 工作也無法看見它,sudo 同樣找不到它,因為 /etc/sudoers 中的 secure_path 會以固定清單取代 PATH。如果某項工具應供整台機器使用,請將它全域安裝。

sudo pipx install --global ansible
sudo pipx ensurepath --global

--global 旗標會將環境放在 /opt/pipx,並將可執行檔連結至 /usr/local/bin;該路徑位於預設的 PATH 中,也位於 secure_path 內。請先使用 pipx --version 檢查版本,因為 Ubuntu 24.04 提供的 pipx 版本是 1.4.3,比 --global 舊,而較舊的 pipx 會回應 unrecognized arguments: --global。在該版本中,請自行設定文件所述的 2 個目錄:

sudo env PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install ansible
command -v ansible

command -v ansible 應輸出 /usr/local/bin/ansible。如果輸出的是 /home 下的路徑,表示該工具已安裝到單一使用者的帳號中,任何服務都找不到它。

想使用 lockfile 時選擇 uv

uv 是 Astral 提供的單一執行檔,涵蓋 pip、venv 與 pip-tools 的功能,也能下載 Python interpreter。它的速度足以讓小型 VPS 感受到差異,並且會寫入真正的 lockfile。

官方安裝程式會將 uv 與 uvx 放入 ~/.local/bin:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv --version

在伺服器上將指令碼透過管線傳給 shell 執行前,應先確認內容。請在 URL 中固定版本,並在執行前閱讀檔案:

curl -LsSf https://astral.sh/uv/0.12.3/install.sh -o uv-install.sh
less uv-install.sh
sh uv-install.sh

如果系統已安裝 pipx,也可以使用 pipx install uv。uv 是不依賴自身 Python 環境的獨立執行檔,因此將它複製到 /usr/local/bin,即可讓主機上的所有使用者共用。

對於包含 pyproject.toml 的專案,工作流程只需4個指令,而且只有最後一個會在伺服器上執行。

uv init myapp
uv add flask gunicorn
uv lock
uv sync --frozen --no-dev

uv lock 會寫入 uv.lock。這是跨平台的 lockfile,包含確切的解析版本;請將它與程式碼一同提交。uv sync 會在專案根目錄建立 .venv,使其符合 lockfile。在伺服器上,--frozen 是關鍵旗標:文件將其定義為以 lockfile 中的版本作為唯一依據,而不是檢查 lockfile 是否為最新。這正是部署所需的行為。--no-dev 不會安裝開發相依性群組。

現有的 requirements.txt 專案不需要轉換,因為 uv 使用 pip 的語法:

uv venv /srv/myapp/.venv
uv pip install --python /srv/myapp/.venv/bin/python -r /srv/myapp/requirements.txt

產生的會是一般的虛擬環境,差別在於 uv 不會在其中安裝 pip。因此,除非使用 uv venv --seed 建立環境,否則 .venv/bin/pip 與 .venv/bin/python -m pip 無法運作。請改用 uv pip 安裝。本文後續不會在該環境中執行 pip,因此也不會造成其他變更。

在伺服器上使用 uv 前,還有一個預設值值得了解。其 python-preference 設定預設為 managed。文件說明,這會優先選擇「由 uv 下載並安裝的 interpreter」,而非系統上已存在的 interpreter。因此,在只提供3.12的主機上執行 uv venv --python 3.13 時,uv 會安靜地將3.13 下載至 ~/.local/share/uv/python,而不是直接失敗。這在筆記型電腦上很方便,在伺服器上卻可能造成意外,因為服務會依賴位於家目錄中的 interpreter,而 apt upgrade 永遠不會為它套用修補程式。若要使用發行版提供的 interpreter,請在 uv.toml 中將 python-preference 設為 only-system。若要將環境放在專案根目錄以外,UV_PROJECT_ENVIRONMENT 可指定專案虛擬環境所使用的目錄。

將 systemd 指向 venv 解譯器,而不是 activate

這是多數 Python 部署失敗的地方,原因在於誤解 activate 的作用。

bin/activate 是 shell 指令碼。它會將 venv 的 bin 目錄加到 PATH 的開頭,設定 VIRTUAL_ENV,儲存舊值以便 deactivate 還原,並變更提示字元。它不包含任何解譯器本身會讀取的內容。啟用環境只是方便使用者在提示字元輸入 python。

真正選擇環境的是你執行的解譯器檔案。/srv/myapp/.venv/bin/python 啟動時,Python 的 site 模組會在存放可執行檔的目錄及其上一層目錄尋找 pyvenv.cfg 檔案。找到 /srv/myapp/.venv/pyvenv.cfg 後,sys.prefix 會被設為 venv,讓該 venv 的 site-packages 加入 sys.path。這就是完整機制。它不需要環境變數,也不需要 shell。

因此,這個單元完全不會啟動:

[Service]
ExecStart=source /srv/myapp/.venv/bin/activate && gunicorn app:app
myapp.service: Failed to locate executable source: No such file or directory
myapp.service: Failed at step EXEC spawning source: No such file or directory
myapp.service: Main process exited, code=exited, status=203/EXEC

ExecStart 不是 shell 命令列。systemd 會直接執行程式,因此沒有 source 內建命令,&& 會以字面值引數傳入,也不會進行 shell 的展開處理;systemd 自身明確說明的少數展開除外。

而這個單元會啟動,接著結束:

[Service]
ExecStart=/usr/bin/python3 /srv/myapp/app.py
ModuleNotFoundError: No module named 'flask'

/usr/bin/python3 是系統解譯器,其 sys.path 從未包含你的 venv。相同命令在 SSH 工作階段中能執行,只是因為你當時已啟用 venv,所以 shell 會透過 PATH 解析 python3,改為使用 .venv/bin/python3。

將命令包在 /bin/bash -c 'source ... && gunicorn ...' 中確實可行。但這會讓 systemd 與你的程序之間多一層沒有必要的 shell;只要使用一個絕對路徑即可:

[Unit]
Description=myapp web service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=myapp
Group=myapp
WorkingDirectory=/srv/myapp
Environment=PYTHONUNBUFFERED=1
Environment=PATH=/srv/myapp/.venv/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/srv/myapp/.venv/bin/gunicorn --workers 3 --bind 127.0.0.1:8000 app:app
Restart=on-failure
RestartSec=5
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=full

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now myapp
systemctl status myapp
journalctl -u myapp -n 50 --no-pager

systemctl status myapp 應回報 active (running),且 Main PID 中應包含你的 gunicorn 程序。若結果不同,請查看 journal。

Environment=PATH= 那一行不是給 ExecStart 使用的,因為 ExecStart 已經包含完整路徑。它是給應用程式啟動的程序使用的。服務會從 systemd 繼承精簡的預設 PATH,因此 Python 程式呼叫 subprocess.run(["ffmpeg", ...]),或透過 shell 執行 venv 中的主控台指令碼的管理命令,都可能找不到所需內容。將 venv 的 bin 目錄放在最前面,是服務確實會使用 activate 的唯一部分。使用 systemctl show -p Environment myapp 檢查該單元實際收到的內容。

相同規則也適用於排程工作。在 Ubuntu 中,cron 不會將 shell 或 daemon 的 PATH 傳給工作:除非 crontab 自行設定 PATH,否則每項工作都會取得編譯時內建的預設 /usr/bin:/bin,而 /etc/environment 不會覆寫它。該值不會包含你的 venv,因此 crontab 中寫成 python3 /srv/myapp/cleanup.py 的那一行會執行系統解譯器,並在凌晨 3 點因 ModuleNotFoundError 而失敗。cron 會將錯誤寄給 crontab 的擁有者,或寄到你設定的 MAILTO 位址;在多數伺服器上,這表示沒有人讀取的本機信箱。若未安裝郵件程式,cron 會丟棄輸出,只將 No MTA installed, discarding output 寫入系統日誌。也請在那裡使用 venv 的絕對路徑。若要讓輸出進入 journal,並改為保留上次執行的記錄,systemd 服務與計時器配對會使用相同的 ExecStart 行。

Docker 是否取代了這項決策?

容器擁有獨立的檔案系統,因此問題的形式改變了,但本質依然存在。在如 python:3.12-slim 這類官方映像檔中,Python 已內建於 /usr/local 且不帶有 EXTERNALLY-MANAGED 標記,因此以 root 身分執行 pip install 是新增套件的預期方式,此時 venv 的幫助有限。若改為建置 FROM ubuntu:24.04,您會在映像檔內再次遇到 externally-managed-environment,原因與主機端相同:這是發行版提供的直譯器,且帶有發行版的標記檔案。

許多映像檔仍會使用 venv,因為它能簡化多階段建置(multi-stage build)。建置階段(builder stage)將套件安裝至 /opt/venv,執行階段(runtime stage)則僅複製該目錄,並將編譯器留在建置階段。此時,啟用(activate)的問題會隨之而來。RUN source /opt/venv/bin/activate 指令僅影響該建置層的 shell,因此在執行階段,容器會以系統直譯器啟動並引發 ModuleNotFoundError。請設定 ENV PATH="/opt/venv/bin:$PATH",或為 CMD 提供絕對路徑 /opt/venv/bin/gunicorn。這與 systemd 的問題相同,只是發生在不同的檔案中。

因此,容器取代了直譯器的問題,因為映像檔會鎖定直譯器及其下方的所有內容。但它並未取代鎖定(pinning)的問題。若映像檔是從未鎖定的 requirements.txt 建置而成,下個月解析出的版本將會不同,這意味著映像檔標籤(tag)雖可重現,但產生該映像檔的建置過程卻無法重現。無論是否使用容器,像 uv.lock 這類鎖定檔(lockfile)或完全鎖定的需求檔案,才是彌補此差距的關鍵。當單一應用程式在 VPS 上透過 systemd 執行時,容器化通常只是將相同的決策轉移至 Dockerfile,因為 systemd 本身已能重啟失敗的處理程序並將輸出擷取至 journal。在 VPS 上執行 Docker 的價值在於,當您希望將建置好的映像檔本身作為部署標的時,它便能發揮作用。

FAQ

可以直接使用 pip install 搭配 --break-system-packages 嗎?

不建議用在必須持續運作的伺服器上。這個旗標的作用正如其名稱所示:移除保護機制,讓 pip 寫入 /usr/local/lib/python3.12/dist-packages;而該路徑在 sys.path 的 apt 目錄之前。之後,您安裝的版本會遮蔽所有在 /usr/bin/python3 下執行的系統指令所使用的發行版版本,而 apt 仍認為自己管理的版本已安裝。因此,在發生故障前,沒有任何機制會偵測到衝突。若是在每次都從頭重建的容器映像中使用,影響會限制在該映像內,因此尚可接受。在您需要維護的主機上,請建立 venv。只需一個指令。

虛擬環境應放在伺服器上的哪個位置?

放在應用程式自己的目錄內,例如 /srv/myapp/.venv,由 deploy 使用者擁有,且服務帳號僅具備讀取與執行權限。每個應用程式各自使用一個 venv,因為共用 venv 可能讓第一個應用程式的升級作業破壞第二個應用程式。建立 venv 後,不要移動或複製它:其 bin/ 目錄中的每個 entry-point 指令碼,都會在 shebang 行中寫入該絕對路徑,因此移動 venv 後會因 bad interpreter: No such file or directory 而失敗。請刪除它,改從 requirements.txt 重新建置。

為什麼我的 systemd 服務會因 ModuleNotFoundError 而失敗?

因為該 unit 執行的 interpreter 不是 venv 中的 interpreter。執行 systemctl cat myapp,並查看 ExecStart。其中必須以絕對路徑指定 /srv/myapp/.venv/bin/python,或指定同一個 bin/ 目錄中的 console script。直接在 ExecStart 中載入 activate 無法運作,因為 ExecStart 不是 shell,而 systemd 會以 status=203/EXEC 回報 Failed to locate executable source。加入 Environment=PATH=/srv/myapp/.venv/bin:/usr/local/bin:/usr/bin:/bin,讓程式啟動的任何 subprocess 也能找到 venv 中的工具。

我應該改用 uv,而不是 venv 和 pip 嗎?

如果您需要 lockfile、安裝時間慢到影響工作,或需要使用發行版未提供的 Python 版本,可以使用 uv。它會建立一般的 venv,因此 systemd unit 與檔案配置不會改變,而 uv sync --frozen 會完全依照 lockfile 的記錄進行安裝。如果單一應用程式從 git 部署,使用固定版本的 requirements.txt,且安裝只需幾秒,python3 -m venv 就已經足夠,也能少維護一個需要在伺服器上更新的 binary。

這篇文章對您有幫助嗎?

#python#venv#pipx#uv#deployment