上一级 syhdtc668 / notebook

NOTE · Engineering Systems

Ubuntu 与 Python GPU 环境：先锁版本，再安装

用可复现的版本矩阵配置 Ubuntu、Python、NVIDIA 驱动、CUDA 与 PyTorch，避免把不同年代的命令混在一起。

整理于 9 min read 4129 字词
#Ubuntu#Python#CUDA#PyTorch#环境配置

历史环境中曾同时使用 Ubuntu 20.04、CUDA 11.8、CUDA 12.5 和不同版本的 cuDNN。单独看每条命令未必错，但拼成一套环境就会互相冲突。更稳的原则是：先锁版本矩阵，再执行安装。

1. 先收集事实

不要先改源、卸驱动或覆盖 /usr/local/cuda。先保存以下输出：

lsb_release -ds
uname -r
lspci -nnk | grep -A3 -i 'vga\|3d\|display'
nvidia-smi
nvcc --version
python3 --version
python3 -m pip --version

这里要区分三件事：

  • nvidia-smi 主要反映正在工作的驱动及其可支持的 CUDA 上限；
  • nvcc --version 反映本机 CUDA Toolkit；
  • torch.version.cuda 反映当前 PyTorch 构建使用的 CUDA 运行时版本。

三者不要求显示完全相同的数字。是否兼容应查 NVIDIA 和框架的正式矩阵，不能靠“数字越接近越好”判断。

2. 建立项目级 Python 环境

venv

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip --version

退出环境：

deactivate

Conda

conda create -n PROJECT_ENV python=PYTHON_VERSION
conda activate PROJECT_ENV
python -m pip --version

PROJECT_ENV 和 PYTHON_VERSION 都是占位符。不要把研究项目长期堆进 base 环境，也不要混用环境外的 pip。

PyTorch 从 2.6 起不再发布官方 Conda channel 包。当前版本应以 PyTorch 安装选择器给出的命令为准；Conda 仍可用于管理 Python 环境，框架本身可在环境内用 python -m pip 安装。

3. GPU 环境的版本矩阵

安装前至少写下这张表：

层需要确定的内容证据来源
操作系统发行版、版本、架构lsb_release、uname -m
内核与驱动内核、NVIDIA 驱动uname -r、nvidia-smi
Toolkit是否真的需要本机 nvcc项目编译要求
Python框架支持的版本框架官方安装页
框架CPU/CUDA 构建及版本官方安装选择器

如果只是运行官方 PyTorch wheel，通常不应先假定必须单独安装完整 CUDA Toolkit；只有编译 CUDA 扩展或其他 CUDA 项目时，才需要进一步核对本机编译工具链。

NVIDIA 官方建议优先使用发行版包管理器对应的安装方式，并明确要求操作系统、编译器和 Toolkit 版本互相支持。具体步骤见 CUDA Installation Guide for Linux。不要把 .run 安装和 APT 安装随意混用。

4. PyTorch 安装后的验证

python - <<'PY'
import sys
import torch

print("python:", sys.executable)
print("torch:", torch.__version__)
print("torch CUDA runtime:", torch.version.cuda)
print("CUDA available:", torch.cuda.is_available())
if torch.cuda.is_available():
    print("device:", torch.cuda.get_device_name(0))
PY

验证的重点不是“命令没有报错”，而是：解释器路径正确、导入的是目标环境中的包、GPU 可用性符合预期。

定位包来源：

python -m pip show torch
python -c 'import torch; print(torch.__file__)'

5. pip/Conda 混乱时的排查顺序

command -v python
command -v pip
python -m pip --version
python -m site
conda info --envs

常见根因：

  1. 终端没有激活预期环境；
  2. pip 和 python 不属于同一个环境；
  3. IDE 选择了另一个解释器；
  4. 用户目录、系统目录和 Conda 目录里存在同名包；
  5. shell 缓存了旧命令路径，可用 hash -r 后重查。

优先使用：

python -m pip install PACKAGE_NAME
python -m pip uninstall PACKAGE_NAME

不把 sudo pip、修改系统 pip 指向、手工删 site-packages 当作通用解决办法。现代项目的 editable install 使用：

python -m pip install -e .

卸载时仍使用项目声明的包名：

python -m pip uninstall PACKAGE_NAME

6. 可复现性记录

完成配置后保存最小证据：

python -m pip freeze > requirements-lock.txt
conda env export --from-history > environment-history.yml
nvidia-smi > nvidia-smi.txt

pip freeze 是环境快照，不等同于经过设计的依赖声明；conda --from-history 更适合记录主动选择的顶层包。二者一起保留，后续排错更有价值。

7. Ubuntu 安装与软件源备忘

历史安装中使用过 Ubuntu 20.04 的完整 focal 源列表，以及在 GRUB 中临时加入 nomodeset、acpi=off 的做法。这些内容可以帮助理解当时的过程，但不能跨机器照抄：

  • 软件源必须与当前发行版代号完全一致，可先用 lsb_release -cs 或读取 /etc/os-release 确认版本；
  • 更换软件源前先备份现有配置，并使用镜像站针对当前版本生成的配置，不把旧 focal 条目写进新版本系统；
  • nomodeset 只适合定位早期显卡初始化问题，可能导致图形性能和分辨率受限；
  • acpi=off 会关闭重要的电源与硬件管理能力，只能作为极短暂的诊断实验，不能作为常驻启动参数；
  • 不要在没有理解磁盘布局和启动模式时照抄双系统分区或 GRUB 修改步骤。

Ubuntu 安装与启动故障应优先参考 Ubuntu 官方安装文档和当前硬件厂商资料。使用国内镜像时，可在 TUNA Ubuntu 镜像帮助中选择当前版本。

安装完成后，先完成常规更新：

sudo apt update
apt list --upgradable

是否执行完整升级应结合远程连接、内核/驱动变更和回滚条件判断。生产或实验主机不应把系统大版本升级混在环境安装步骤里。

NVIDIA 驱动

先查看设备和 Ubuntu 推荐项：

lspci -nnk | grep -A3 -i 'vga\|3d\|display'
ubuntu-drivers devices

Ubuntu 仓库驱动、NVIDIA CUDA 仓库驱动和 .run 安装包是不同管理路径，不应混装。apt purge nvidia-*-555 只匹配特定分支，不能作为通用卸载命令；手工 .run 安装也不应列为默认方案。需要安装或切换驱动时，以当前 Ubuntu 和 NVIDIA 官方说明为准，并在变更前确认远程恢复手段。

8. 桌面开发工具

这些工具不是 GPU 环境的依赖，但仍可作为安全的桌面备忘。

PyCharm

安装方式和目录会随发行版变化，优先参考 JetBrains 安装指南。如果使用解压版并需要桌面入口，可创建用户级文件 ~/.local/share/applications/pycharm.desktop：

[Desktop Entry]
Version=1.0
Type=Application
Name=PyCharm
Icon=/PATH_TO_PYCHARM/bin/pycharm.svg
Exec=/PATH_TO_PYCHARM/bin/pycharm.sh %f
Terminal=false
Categories=Development;IDE;

/PATH_TO_PYCHARM 是占位符。保存后检查该路径确实存在；不要把个人主目录写进公开示例。

常见排查入口：

  • 字体、工具栏和终端外观在 IDE 设置中调整，不修改安装目录；
  • Git 推送证书错误应修复系统 CA、代理 CA 或 Git 配置，不关闭 TLS 校验；
  • pytest 被误设为默认运行器时，在项目的 Python Integrated Tools 中核对测试框架；
  • 结束无响应 IDE 前先保存工作，并用 pgrep -af pycharm 确认目标进程。

常用桌面软件

sudo apt install vlc
sudo apt install terminator
sudo apt install gnome-system-monitor

安装前可用 apt-cache policy PACKAGE_NAME 查看候选版本。FSearch 可参考其官方仓库选择适合当前发行版的安装方式；搜狗输入法应以其Linux 官方指南为准。

Qt4/Dukto PPA 和 indicator-sysmonitor PPA 已经陈旧，本文不把它们列为当前命令；第三方 PPA 还会扩大系统软件源的信任面。局域网文件传输可优先使用 SSH/SFTP、局域网共享或仍在维护的工具。

双系统时间

先观察当前状态：

timedatectl status

一种历史配置是使用 ntpdate time.windows.com 后把硬件时钟改成本地时间。这不是唯一方案，也可能与当前时间同步服务冲突。更稳妥的做法是先确定 Windows 与 Linux 对硬件时钟采用 UTC 还是本地时间，再只选择一种一致策略；不要同时运行多个 NTP 客户端。

9. pip 与 Conda 镜像

镜像是下载源，不会解决 Python 版本或二进制兼容问题。临时使用镜像时优先显式写在单次命令中：

python -m pip install --index-url https://pypi.tuna.tsinghua.edu.cn/simple PACKAGE_NAME

需要长期配置时，先查看配置来源：

python -m pip config debug
python -m pip config list

TUNA 的当前配置方式见 PyPI 镜像帮助。企业环境还要确认代理、内部索引和 CA 要求，不能通过增加 trusted-host 或关闭 TLS 验证绕过证书问题。

Conda 镜像配置同样以 TUNA Anaconda 帮助为准。旧 pkgs/free、pkgs/pro channel 已不适合作为当前模板，也不要为了使用镜像就盲目删除 defaults。修改前后可保存并检查：

conda config --show-sources
conda config --show channels

10. Python 科学计算资源索引

Python 环境部分主要是一组书签。为降低第三方文章失效的影响，下面优先列出相同主题的上游文档入口：

Matplotlib 的字体名称依赖本机实际安装字体。遇到缺字时先列出可用字体，不把某台机器上的字体族名称当成跨平台默认值。

11. 历史资源与书签

下面按主题整理历史书签。它们用于追溯解决问题的资料，不表示其中的版本、命令或下载仍适合当前系统。执行前应对照当前 Ubuntu、Python、CUDA、IDE 和库的官方文档；尤其不要照抄关闭证书校验、系统级 pip、旧驱动清理或手工覆盖库文件等做法。

Ubuntu 安装、启动与桌面

Python、CUDA、cuDNN 与 Conda

PyCharm 历史书签

pip 与 Python 运行环境历史书签

Python 2 pip 报错截图作为历史图片放在页末，不计入书签链接；它只用于识别旧环境，不表示应重新执行图中的命令。

NumPy 历史书签

PyTorch 历史书签

Matplotlib 历史书签

SciPy、OpenCV 与 Anaconda 历史书签

索引使用原则

  1. 上述链接是历史检索入口，不代表本站为第三方内容背书。
  2. 第三方文章中的命令应先与当前官方文档、本机版本和现有配置核对。
  3. 直接脚本、驱动、PPA、系统源和卸载教程风险高于普通 API 说明，应先只读检查再操作。
  4. 链接失效时保留标题也有助于检索原主题；不要改为来历不明的网盘镜像。

12. 历史命令与当前边界

以下旧内容仍有历史背景价值，但不再作为当前可执行教程：

  • 锁定 Ubuntu 20.04 的整份软件源清单；
  • 相互冲突的 CUDA 11.8/12.5 环境变量与 cuDNN 手工复制步骤；
  • 旧 pkgs/free、pkgs/pro Conda 镜像配置；
  • 系统级 sudo pip、Python 2 get-pip.py 和手工修改包目录的方法；
  • Qt4/Dukto 等停止维护链路。

Python 2.7 与 get-pip.py 终端记录，仅用于识别历史环境

这些历史记录解释了旧环境为何能运行，但恢复时必须放进隔离、锁版本的复现环境，不能与当前项目环境拼接。