在 Ubuntu 24.04 VPS 上使用 Python、pip 和虚拟环境

Ubuntu 24.04 自带 Python 3.12，但直接用 pip 安装软件包现在会报 “externally-managed-environment” 错误。解决办法是把每个项目隔离在各自的虚拟环境中。本指南演示如何准备您的 VPS Linux Infrawire、规范地管理依赖，并让应用作为 systemd 服务持续运行。

📋 前提条件

一台运行 Ubuntu 24.04 或 Debian 12 的 VPS，并拥有 root SSH 权限（IP 地址和 root 密码可在您的客户区找到）
一个 Python 项目，或一个用于测试的简单脚本
具备基本的命令行知识

1. 安装 Python 3、pip 和 venv

Python 3 通常已预装，但 pip 和 venv 模块是单独的软件包。

Bash
1apt update
2apt install -y python3 python3-pip python3-venv python3-dev build-essential
3python3 --version
4pip3 --version

2. 理解 PEP 668 错误

在 Ubuntu 24.04 或 Debian 12 上以 root 身份运行 pip install requests 会输出：

TEXT
error: externally-managed-environment

这项保护机制（PEP 668）可以防止 pip 覆盖由 apt 管理的文件而破坏系统工具。请不要用 --break-system-packages 绕过它，而应使用下面三种规范做法之一。

3. 创建虚拟环境

虚拟环境是为单个项目准备的 Python 和 pip 私有副本。

Bash
1mkdir -p /opt/myapp && cd /opt/myapp
2python3 -m venv venv
3source venv/bin/activate
4pip install --upgrade pip
5pip install requests flask gunicorn

命令提示符现在以 (venv) 开头。用 deactivate 退出该环境。

4. 使用 requirements.txt 管理依赖

固定精确的版本号，以便在另一台服务器上完全一致地重建项目。

Bash
1pip freeze > requirements.txt
2# 在全新的机器上
3python3 -m venv venv
4source venv/bin/activate
5pip install -r requirements.txt

5. 使用 pipx 安装命令行工具

对于独立工具（httpie、yt-dlp、black 等），pipx 会为每个工具提供独立的隐藏虚拟环境，并把命令暴露为全局可用。

Bash
1apt install -y pipx
2pipx ensurepath
3pipx install httpie

之后请重新打开一个 shell，以加载更新后的 PATH。对于有 Debian 软件包的库，apt install python3-requests 也是可行的选择。

6. 将应用作为 systemd 服务运行

先创建一个无特权的专用用户，再编写一个使用虚拟环境中解释器的 unit（这里以 Gunicorn 运行 app.py 中名为 app 的 Flask 对象为例）。

Bash
1useradd --system --home /opt/myapp --shell /usr/sbin/nologin myapp
2chown -R myapp:myapp /opt/myapp

创建 /etc/systemd/system/myapp.service：

INI
1[Unit]
2Description=My Python application
3After=network.target
4
5[Service]
6User=myapp
7WorkingDirectory=/opt/myapp
8ExecStart=/opt/myapp/venv/bin/gunicorn --bind 127.0.0.1:8000 app:app
9Restart=on-failure
10RestartSec=5
11
12[Install]
13WantedBy=multi-user.target

Bash
1systemctl daemon-reload
2systemctl enable --now myapp

在 8000 端口前部署 nginx 等反向代理，即可将应用发布到互联网。

✅ 验证

Bash
1which python   # 激活后必须指向 /opt/myapp/venv 内部
2pip list
3systemctl status myapp --no-pager
4journalctl -u myapp -n 50 --no-pager
5curl -I http://127.0.0.1:8000

🔧 故障排查

The virtual environment was not created successfully because ensurepip is not available：缺少 venv 软件包。用 apt install python3-venv（或 python3.12-venv）安装后重新执行命令。

systemd 中出现 status=203/EXEC：ExecStart 中的路径有误，或服务用户无权执行该文件。用 ls -l /opt/myapp/venv/bin/gunicorn 以及前面设置的属主进行检查。

仅在 systemd 下出现 ModuleNotFoundError：服务使用了系统 Python 而不是虚拟环境。请始终在 ExecStart 中调用 /opt/myapp/venv/bin/python 或 venv/bin 下的可执行文件。

pip: command not found：改用 python3 -m pip，或先激活虚拟环境。

🎉 您的 Python 项目现在已实现隔离、可复现，并作为可靠的服务稳定运行！