Ubuntu 服务器 Python 环境管理:venv、pipx 与 uv 对比
在 Ubuntu 24.04 上运行 pip install 遇到 externally-managed-environment 错误?本文解析 PEP 668 限制,教你根据应用类型选择 venv、pipx 或 uv,并提供配置 systemd 的最佳实践。
在全新的 Ubuntu 服务器上运行 pip install 失败的原因
在服务器上选择 Python venv、pipx 还是 uv,取决于一个问题:您要安装什么。应用依赖项应放在应用自身目录中的虚拟环境内。需要通过名称直接运行的命令行工具应使用 pipx。uv 可以完成这两项工作,并额外提供 lockfile;当第二台机器需要构建相同环境时,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 增强提案 668,“外部管理的环境”)在发挥作用。Debian 和 Ubuntu 会在解释器旁边的 /usr/lib/python3.12/EXTERNALLY-MANAGED 放置一个标记文件。对于包含该文件的解释器,pip 拒绝写入。
该规则存在的原因是 sys.path 顺序。apt 会将库安装到 /usr/lib/python3/dist-packages。以 root 身份针对系统解释器运行的 pip 会写入 /usr/local/lib/python3.12/dist-packages,而 Debian 的打包配置会让该目录在搜索路径中排在更前面。使用 python3 -c 'import sys; print(sys.path)' 自行打印并查看顺序。因此,对于系统中通过 /usr/bin/python3 运行的每个程序,包括发行版自身的工具,pip 写入的副本都会覆盖 apt 安装的副本。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中创建一个链接。 - 需要锁定文件、更快安装速度,或需要发行版未提供的 Python 版本的项目:使用 uv。它会生成一个普通的 venv,以及一个
uv.lock文件。 - 发行版工具需要使用、而不是你的代码需要使用的库:
sudo apt install python3-<name>,这是向系统解释器添加任何内容的唯一受支持方式。
pipx 和 uv tool install 执行相同的任务,因此已经安装 uv 的主机不需要再安装 pipx。选择哪种 Web 框架不会改变这一点:在 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/ 中的每个入口点脚本都包含绝对 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 的符号链接。升级发行版后,如果该路径现在指向更新版本的 Python,新解释器会在 lib/python3.13 目录中查找软件包,而 venv 中没有该目录,因此服务启动时会因 ModuleNotFoundError 而退出。这两种情况的修复方法相同:删除 venv,然后从 requirements.txt 重新创建。重建只需几秒钟。切勿在不同机器之间复制 venv。
虚拟环境的位置及其所有者
将虚拟环境放在 /srv/myapp/.venv 的代码旁边,并为每个应用单独使用一个虚拟环境。这样,整个部署就是一个目录,systemd 单元使用的路径不会变化,两个应用也不会因共享依赖升级而相互影响。不要将虚拟环境放在 Web 服务器会直接发布文件的目录中,因为其中包含依赖项,通常还包含配置。
所有权问题也只需花半分钟处理。让 deploy 用户拥有代码和虚拟环境,并仅授予服务账户读取和执行权限。
sudo adduser --system --group --no-create-home myapp
sudo chown -R deploy:myapp /srv/myapp
sudo chmod -R o-rwx /srv/myapp现在,服务可以导入依赖项,但无法改写这些依赖项。这意味着 Web 应用中的代码执行漏洞无法静默替换磁盘上的库,并在服务重启后继续存在。有关如何将同样的原则应用于计算机上的其他服务,请参阅以最小权限用户运行服务。
用于命令行工具的 pipx
pipx 用于安装应用程序,不用于安装库。每个工具都会在 ~/.local/share/pipx/venvs/<name> 下拥有独立环境,该工具的可执行文件则链接到 ~/.local/bin,因此需要同一个库的不同版本的两个工具不会相互冲突。
sudo apt update
sudo apt install -y pipx
pipx ensurepath
pipx install httpiepipx 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 同样找不到它,因为 secure_path 会在 /etc/sudoers 中使用固定列表替换 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。在该版本中,请手动设置这两个文档规定的目录:
sudo env PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install ansible
command -v ansiblecommand -v ansible 应输出 /usr/local/bin/ansible。如果输出的是 /home 下的路径,说明该工具安装到了单个用户的账户中,服务将无法找到它。
uv:需要锁定文件时
uv 是 Astral 提供的单一二进制文件,涵盖 pip、venv 和 pip-tools 的功能,还可以下载 Python 解释器。它的速度足够快,在小型 VPS 上也能体现出差异,并且会生成真正的锁定文件。
官方安装程序会将 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-devuv lock 会写入 uv.lock。这是一个跨平台锁定文件,其中保存了解析后的确切版本,应将它与代码一起提交。uv sync 会在项目根目录中生成 .venv,使其与锁定文件一致。在服务器上,--frozen 是关键选项:文档将其定义为以锁定文件中的版本为准,而不是检查锁定文件是否为最新版本。这正是部署所需的行为。--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 下载并安装的解释器”,而不是系统中已有的解释器。因此,在只提供 3.12 的服务器上运行 uv venv --python 3.13 时,uv 会将 3.13 静默下载到 ~/.local/share/uv/python,而不是直接失败。这在笔记本电脑上很方便,但在服务器上可能造成意外,因为服务现在依赖存放在用户主目录中的解释器,而 apt upgrade 永远不会为它打补丁。如果希望使用发行版提供的解释器,请在 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:appmyapp.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/EXECExecStart 不是 shell 命令行。systemd 会直接执行程序,因此不存在 source 内建命令,&& 会作为字面量参数传入,除 systemd 自身文档说明的少数展开外,也不会发生 shell 的任何展开。
而这个单元会启动,然后退出:
[Service]
ExecStart=/usr/bin/python3 /srv/myapp/app.pyModuleNotFoundError: 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.targetsudo systemctl daemon-reload
sudo systemctl enable --now myapp
systemctl status myapp
journalctl -u myapp -n 50 --no-pagersystemctl status myapp 应报告 active (running),并且 Main PID 应是你的 gunicorn 进程。若结果不同,请查看日志。
Environment=PATH= 行并不是为 ExecStart 设置的,因为它已经包含完整路径。它是为应用启动的进程设置的。服务会从 systemd 继承一个较短的默认 PATH,因此,调用 subprocess.run(["ffmpeg", ...]) 的 Python 代码,或通过 shell 调用 venv 中控制台脚本的管理命令,都找不到所需内容。将 venv 的 bin 目录置于开头,是服务确实会使用的 activate 部分。使用 systemctl show -p Environment myapp 检查该单元实际接收到的内容。
相同规则也适用于计划任务。在 Ubuntu 上,cron 不会将 shell 或 daemon 的 PATH 传给任务:除非 crontab 自身设置了 PATH,否则每个任务都会获得编译时默认值 /usr/bin:/bin,而 /etc/environment 不会覆盖它。该默认值从不包含你的 venv,因此,读取 python3 /srv/myapp/cleanup.py 的 crontab 行会使用系统解释器,并在凌晨 3 点因 ModuleNotFoundError 失败。cron 会将错误通过邮件发送给 crontab 的所有者,或者发送到你设置的 MAILTO 地址;在大多数服务器上,这意味着发送到没人读取的本地邮箱。如果未安装邮件程序,cron 会丢弃输出,只将 No MTA installed, discarding output 写入系统日志。这里也应写入 venv 的绝对路径。若要将输出写入日志并保留上次运行记录,则可使用 systemd 服务和计时器单元对,它使用相同的 ExecStart 行。
Docker 会替代这个决策吗?
容器拥有自己的文件系统,因此问题的形式会改变,但不会消失。在 python:3.12-slim 等官方镜像中,Python 已内置于 /usr/local,并且不包含 EXTERNALLY-MANAGED 标记文件,因此以 root 身份通过 pip install 添加软件包是预期做法,venv 的作用很小。改为构建 FROM ubuntu:24.04 后,您会在镜像内部再次遇到 externally-managed-environment,原因与主机上相同:它是发行版提供的解释器,并携带发行版的标记文件。
许多镜像仍然使用 venv,因为这样可以简化多阶段构建。构建阶段将软件包安装到 /opt/venv,运行时阶段只复制这个目录,不保留编译器。激活问题也会随之保留。RUN source /opt/venv/bin/activate 行只影响该构建层的 shell,因此容器运行时会使用系统解释器,并引发 ModuleNotFoundError。设置 ENV PATH="/opt/venv/bin:$PATH",或为 CMD 指定绝对路径 /opt/venv/bin/gunicorn。这与 systemd 中的问题相同,只是位于不同的文件中。
因此,容器会替代解释器选择问题,因为镜像固定了解释器及其下的全部内容。但它不会替代版本固定问题。由未固定的 requirements.txt 构建的镜像下个月可能解析出不同版本,这意味着镜像标签具有可复现性,但生成该镜像的构建过程没有。无论是否使用容器,uv.lock 等锁定文件或完全固定版本的 requirements 文件都可以弥补这一差距。当一个应用在一台 VPS 上通过 systemd 运行时,容器通常只是将同一个决策移入 Dockerfile,因为 systemd 已经可以重启失败的进程,并将其输出记录到 journal 中。在 VPS 上运行 Docker 在您希望将构建好的镜像本身作为部署对象时才更有价值。
FAQ
可以直接使用带有 --break-system-packages 的 pip install 吗?
不建议在必须持续运行的服务器上这样做。该标志的作用正如其名称所示:移除保护机制,让 pip 写入 /usr/local/lib/python3.12/dist-packages;该路径在 sys.path 上排在 apt 目录之前。这样,您安装的版本会覆盖所有以 /usr/bin/python3 身份运行的系统脚本所使用的发行版版本,而 apt 仍认为自身的版本已安装。因此,在发生故障之前,不会有任何机制检测到冲突。在每次都从头构建的容器镜像中,影响范围只到该镜像,因此这种做法尚可接受。在您需要长期维护的机器上,请创建 venv。只需一条命令。
虚拟环境应放在服务器的什么位置?
将其放在应用自己的目录中,例如 /srv/myapp/.venv。目录由 deploy 用户拥有,服务账户仅具有读取和执行权限。每个应用使用一个独立的 venv,因为共享 venv 会导致第一个应用的升级破坏第二个应用。创建 venv 后,不要移动或复制它:bin/ 目录中的每个入口脚本都会在 shebang 行中写入该绝对路径,因此移动后的 venv 会因 bad interpreter: No such file or directory 而失败。请删除它,然后从 requirements.txt 重新构建。
为什么我的 systemd 服务因 ModuleNotFoundError 启动失败?
因为该单元执行的解释器不是 venv 中的解释器。运行 systemctl cat myapp 并读取 ExecStart。它必须通过绝对路径指定 /srv/myapp/.venv/bin/python,或指定同一个 bin/ 目录中的控制台脚本。直接在 ExecStart 中加载 activate 无法生效,因为 ExecStart 不是 shell,systemd 会报告 Failed to locate executable source 和 status=203/EXEC。添加 Environment=PATH=/srv/myapp/.venv/bin:/usr/local/bin:/usr/bin:/bin,这样代码启动的任何子进程也能找到 venv 中的工具。
应该使用 uv 代替 venv 和 pip 吗?
如果您需要锁定文件、安装速度慢到影响工作,或者需要使用发行版未提供的 Python 版本,可以使用 uv。它会创建普通的 venv,因此 systemd 单元和文件布局无需改变,而 uv sync --frozen 会严格安装锁定文件中记录的内容。如果单个应用从 git 部署,使用固定的 requirements.txt,并且安装只需几秒,那么 python3 -m venv 已经足够,而且服务器上少维护一个需要更新的二进制文件。