同一台 Linux 服务器可以同时存在系统 Python、Conda 环境和多个项目虚拟环境。包已经安装却无法导入,常见原因是安装时与运行时使用了不同的解释器。

本文的命令均在服务器 Bash 终端执行,示例项目目录为 ~/projects/demo。远程连接和服务器开发流程见 AI Coding指南。

1 解释器、pip 与 PATH

python 是 Shell 根据命令查找规则找到的程序,通常由 PATH 中目录的先后顺序决定。pip 也是一个命令,它关联的 Python 不一定与当前 python 相同。

开始安装前,先查看实际程序位置:

1
2
3
4
5
command -v python
command -v python3
python3 --version
python3 -c "import sys; print(sys.executable)"
python3 -m pip --version

系统可能只有 python3,也可能没有为它安装 pip。输出中的路径和版本,比终端提示符是否显示环境名称更能说明实际情况。

python -m pip 表示用这个 python 解释器运行 pip 模块;后续安装和运行都使用同一个解释器,可以减少环境错配。它不会自动判断项目应该使用哪个 Python。

激活环境主要改变当前 Shell 的命令搜索路径等变量,不会给整台服务器“切换 Python”,也不会更改其他已经运行的终端或进程。sys.executable 的含义见 Python sys 文档。

2 为项目建立 venv

2.1 选择创建环境的 Python

venv 使用已有 Python 创建隔离的包目录,不负责下载另一个 Python 版本。先确认项目要求,再选择符合要求的解释器。

以下以服务器现有 python3 已满足项目要求为前提:

1
2
3
4
5
mkdir -p ~/projects/demo
cd ~/projects/demo
python3 --version
python3 -m venv .venv
source .venv/bin/activate

如果项目要求特定版本,且服务器已安装相应解释器,可使用例如 python3.11 -m venv .venv;版本号需按项目要求替换,不能仅修改目录名来改变 Python 版本。已有 .venv 时应先确认其用途,不要直接拿另一个版本覆盖。

激活后检查解释器和 pip:

1
2
python -c "import sys; print(sys.executable)"
python -m pip --version

路径应指向当前项目的 .venv。venv 的创建和激活机制见 Python venv 文档。

2.2 安装项目依赖

下面假设仓库已有 requirements.txt,并且服务器能访问相应软件源:

1
2
python -m pip install -r requirements.txt
python -m pip check

pip check 检查已安装包声明的依赖是否满足,不会替代项目测试,也不能证明 GPU 或外部系统库可用。若项目使用其他依赖管理方式,应以项目说明为准,不必额外生成一个无关的 requirements 文件。

对于刚创建的个人环境,确有需要时可以用 python -m pip install --upgrade pip 更新 pip;已有稳定实验环境不宜顺手升级全部依赖。

将 .venv/ 加入项目 .gitignore,保留依赖描述文件和源代码。虚拟环境中不要保存唯一一份实验代码或数据。

2.3 退出和再次使用

1
deactivate

下次登录只需进入项目并重新激活,无需每次创建环境:

1
2
cd ~/projects/demo
source .venv/bin/activate

也可以不激活,直接指定解释器路径。例如项目确实有 train.py 时:

1
~/projects/demo/.venv/bin/python ~/projects/demo/train.py

这能固定解释器,但脚本中的相对数据路径仍可能依赖当前目录,运行前需要确认项目约定。

3 使用服务器已有的 Conda

Conda 可以管理环境中的 Python 版本和许多非 Python 依赖。以下假设服务器已经安装 Conda,并按管理员说明加载了相关模块或初始化脚本:

1
2
conda --version
conda env list

若 conda 可用但 conda activate 提示 Shell 未初始化,应先加载这套 Conda 对应的 Shell 支持。已知安装路径时可 source /实际安装路径/etc/profile.d/conda.sh;路径以服务器配置为准,不需要再安装另一套 Conda。

3.1 在个人目录创建环境

下面的 Python 3.11 仅作示例,应按项目兼容范围调整。使用个人路径可避免向共享环境目录写入:

1
2
3
4
5
mkdir -p "$HOME/.conda/envs"
conda create --prefix "$HOME/.conda/envs/research-demo" python=3.11 pip
conda activate "$HOME/.conda/envs/research-demo"
python --version
python -m pip --version

安装会使用当前配置允许的软件源。--prefix 指定的是环境位置;软件包缓存若另有权限或配额限制,仍需按服务器配置处理。参数见 conda create 文档。

如果已经有同名环境,先检查用途,再决定复用还是创建新目录。base 通常承载 Conda 自身与基础工具,尤其不适合作为多人共享的项目安装位置。

3.2 激活与退出

1
2
3
conda activate "$HOME/.conda/envs/research-demo"
python -c "import sys; print(sys.executable)"
conda deactivate

路径形式创建的环境,后续也可使用完整路径激活。一个项目可以选择 venv 或 Conda;在没有特殊需求时,不必再把 venv 套在 Conda 环境里面,避免解释器来源难以追踪。

4 Conda 与 pip 的安装顺序

需要混合使用时,先通过 Conda 安装计划由它管理的依赖,再用环境内的 pip 安装剩余部分。例如,项目需要 NumPy、SciPy,另有专门维护的 requirements-pip.txt:

1
2
3
4
conda activate "$HOME/.conda/envs/research-demo"
conda install numpy scipy
python -m pip install -r requirements-pip.txt
python -m pip check

requirements-pip.txt 是该项目自己的文件,并非 Conda 自动生成;其中应记录需要交给 pip 的依赖。直接让两个工具轮流覆盖同一批包,会增加版本与二进制依赖不一致的可能。

使用 pip 后若还需大幅调整 Conda 依赖,更容易验证的做法是更新环境描述并创建新环境,再重新执行安装和测试。Conda 官方说明见 环境中使用 pip。

项目环境中不使用 sudo pip,也通常不使用 pip install --user。前者可能修改系统安装,后者可能把包放进共享于多个项目的用户包目录,偏离当前环境的隔离目标。

5 记录依赖并重建环境

5.1 记录 pip 环境

在项目环境已经激活、安装和基本测试完成后,记录当前状态:

1
2
3
4
mkdir -p environment-records
python --version > environment-records/python-version.txt
python -m pip --version > environment-records/pip-version.txt
python -m pip freeze > environment-records/requirements-freeze.txt

以上重定向会覆盖同名文件。保存不同实验版本时,可更换目录名;如果项目已使用专门的锁文件工具,应同时保留其锁文件。

pip freeze 导出当前安装包的 requirements 格式记录,通常包含版本约束,但不等同于完整锁文件。它不会锁定操作系统、Python 解释器或 GPU 驱动,也不保证包含可离线安装的包文件;输出中还可能存在本地路径或可编辑安装。具体语义见 pip freeze 文档。

迁移到新位置时,先准备相同或兼容的 Python,再创建新环境。以下假设记录文件已经随项目复制到目标目录:

1
2
3
4
python3 -m venv .venv-rebuild
source .venv-rebuild/bin/activate
python -m pip install -r environment-records/requirements-freeze.txt
python -m pip check

重建后还需执行项目测试。版本相同也可能因平台、编译选项或数据差异表现不同,实验记录应同时保留代码提交号、配置、数据版本和随机种子。

5.2 导出 Conda 环境

在目标 Conda 环境激活后,可分别保存完整导出和主动安装规格:

1
2
3
mkdir -p environment-records
conda env export > environment-records/environment-full.yml
conda env export --from-history > environment-records/environment-history.yml

完整导出包含更详细的包信息,并可包含 pip 包记录;--from-history 主要保留 Conda 历史中主动请求的安装规格,省去求解得到的许多间接依赖,更便于跨平台重新求解,但不是精确锁定。

不要依赖 --from-history 保存通过 pip 安装的全部依赖;这部分应单独维护 requirements 文件,或核对完整 YAML 中的 pip: 段。导出的本机绝对 prefix:、本地包路径及环境名称也应在迁移前检查。说明见 conda env export 文档。

以检查并调整过的完整 YAML 为例,在新位置重建:

1
2
3
4
conda env create --prefix "$HOME/.conda/envs/research-rebuild" \
--file environment-records/environment-full.yml
conda activate "$HOME/.conda/envs/research-rebuild"
python -m pip check

若目标平台不同,完整导出中的构建约束可能无法满足,需要基于主动安装规格重新求解并测试。普通迁移应重建环境,不直接复制 .venv 或 Conda 环境目录;绝对路径和二进制兼容性都会影响复制后的结果。

6 与 VS Code、tmux 和作业脚本配合

VS Code 的 Python 解释器选择、终端激活状态和 Notebook 内核是不同位置的配置。通过 Remote - SSH 打开远端项目后,使用 Python: Select Interpreter 选择服务器上的环境;Notebook 还需检查其内核选择。

在实际运行代码的位置检查:

1
2
import sys
print(sys.executable)

不要仅凭另一个终端里的 pip list 判断当前 Notebook 或调试器使用了哪些包。远程 IDE 的配置见 VS Code Remote - SSH远程开发。

tmux 新窗口、重新 SSH 登录和批处理作业都可能没有继承期望的激活状态。脚本应明确工作目录及环境,例如已经建好 .venv 且项目包含 train.py 时:

1
2
3
4
5
#!/usr/bin/env bash
set -e
cd "$HOME/projects/demo"
source .venv/bin/activate
python -u train.py

若使用 Conda,脚本中应按服务器要求先加载 Conda,再激活目标环境。具体资源申请另按集群规范处理;保持会话的方法见 Linux服务器使用tmux管理长任务。

7 常见问题排查

7.1 已安装却提示 ModuleNotFoundError

先在发生错误的同一个终端、IDE 或内核里确认解释器。以 NumPy 为例:

1
2
3
python -c "import sys; print(sys.executable)"
python -m pip show numpy
python -c "import numpy; print(numpy.__file__)"

如果第一条指向错误环境,应先修正解释器;如果包确实缺失,再按项目依赖安装。导入名称与发行包名称并不总是相同,本地脚本与包重名也可能遮蔽真正的模块,不能把每个报错名称直接当成待安装包名。

7.2 pip 装到了另一个环境

查看 python -m pip --version 输出中的安装路径。使用当前环境的解释器重新安装,并检查是否在另一个终端中激活环境、是否存在自定义命令别名。环境修改不会自动更新已经启动的 Notebook 内核或 Python 进程。

7.3 externally-managed-environment

这通常表示当前解释器由操作系统等外部工具管理,pip 按相应标记限制修改其默认环境。应创建并使用项目 venv,或切换到已有个人 Conda 环境,而不是直接覆盖系统 Python。机制见 Python 外部管理环境规范。

7.4 venv、ensurepip 或 pip 缺失

如果创建时报 No module named venv、ensurepip is not available 等错误,说明所用 Python 安装未提供所需组件。系统 Python 可以由管理员补充对应发行版组件;无 sudo 时可选服务器提供的完整 Python 模块或已有 Conda。

失败后不要继续假设 .venv 已完整建立。先解决解释器来源,再在新的环境目录创建并验证;仅安装一个 pip 包不能补齐所有解释器组件。

7.5 Python 环境正常,但 GPU 不可用

Python 包、CUDA 运行时和服务器 NVIDIA 驱动属于不同层次。安装 PyTorch 等包不会自动替换系统驱动,venv 或 Conda 也不会为进程预约 GPU。

GPU 框架应按项目版本、操作系统与驱动支持范围选择对应安装方式。先确认环境和设备可见性,再检查驱动、调度器分配与框架构建版本。监控和排查方法见 Linux服务器GPU监控与常见问题排查。