Python 环境

为什么每个项目都要独立的环境

不同项目需要的包版本经常冲突：一篇论文的代码要求 torch==2.4，另一个项目要用最新版。全部装进系统 Python，迟早会出现“装了这个，那个就坏了”的情况。虚拟环境给每个项目一套独立的 Python 和包，互不影响，删掉也不影响别的项目。

用哪个工具

工具	推荐场景	说明
uv	新项目的默认选择	速度极快（比 pip 快十倍以上），一个工具同时管理 Python 版本、虚拟环境和依赖，2026 年已经成为 Python 社区的主流推荐
conda（Miniforge）	论文代码给的是 conda 环境文件；需要 conda 才能装的非 Python 依赖	复现别人的代码时常用
pip + venv	了解即可	Python 自带，uv 完全兼容它的用法

不要装 Anaconda

Anaconda 默认的软件源对组织机构（包括不少高校和科研机构）的使用有付费许可要求，已经有高校和研究机构限制或封禁访问。需要 conda 时请安装 Miniforge，它默认使用免费的 conda-forge 源。已经装了 Miniconda 的同学，把软件源改为 conda-forge。

uv

安装

# Linux / Mac / WSL
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装后重新打开终端，运行 uv --version 确认。

国内加速

echo 'export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple' >> ~/.bashrc
source ~/.bashrc

Mac 默认的 shell 是 zsh，把上面的 ~/.bashrc 换成 ~/.zshrc。

用法一：项目模式（推荐）

uv init --python 3.12 my-exp && cd my-exp   # 新建项目并指定 Python 版本（没有会自动下载）
uv add numpy pandas matplotlib  # 添加依赖，自动创建 .venv 并安装，同时写入 pyproject.toml 和 uv.lock
uv add torch torchvision        # PyTorch 的安装注意事项见“GPU 与 CUDA”
uv run python main.py           # 在项目环境里运行
uv sync                         # 别人拿到你的项目后，一条命令装好完全相同的环境

pyproject.toml 和 uv.lock 都要提交到 Git，这样别人和几个月后的你都能复现出一模一样的环境。

用法二：和 pip 一样用

复现别人的代码（只给了 requirements.txt）时：

uv venv --python 3.10           # 在当前目录创建 .venv
source .venv/bin/activate       # 激活（Windows：.venv\Scripts\activate）
uv pip install -r requirements.txt
uv pip freeze > requirements.lock   # 记录装好的精确版本
deactivate                      # 退出环境

激活后，终端提示符前面会出现 (.venv)，此时的 python 和 pip 都指向这个环境。

conda（Miniforge）

安装

# Linux / WSL（x86_64）
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh       # 按提示安装，最后选择 yes 初始化
source ~/.bashrc

Mac 用户下载对应的 MacOSX-arm64 安装脚本；Windows 原生环境可下载 .exe 安装包。

国内下载 conda-forge 包慢的话，按清华镜像的 conda-forge 说明配置镜像。

常用命令

conda create -n exp python=3.11       # 创建名为 exp 的环境
conda activate exp                    # 激活
conda install numpy                   # 用 conda 装包
pip install some-package              # conda 环境里也可以用 pip
conda env export > environment.yml    # 导出环境
conda env create -f environment.yml   # 从文件创建环境（复现论文代码时常用）
conda env list                        # 列出所有环境
conda remove -n exp --all             # 删除环境

原则：一个环境里先用 conda 装好需要 conda 的包，再用 pip 装其余的；不要反复交替混用，否则容易出现依赖冲突。

Jupyter

在环境里安装内核，Jupyter 和 VS Code 才能找到这个环境：

uv add --dev ipykernel                # uv 项目
# 或者在激活的 conda 环境里：conda install ipykernel

在 VS Code 里打开 .ipynb 文件，右上角“选择内核”选中对应的环境即可。在服务器上用 Jupyter 见使用服务器。

VS Code 配置

推荐安装的插件：

插件	作用
Python、Pylance	Python 语言支持、代码补全、类型检查
Jupyter	在 VS Code 里运行 notebook
Ruff	自动格式化和检查代码
Remote - SSH	连接服务器开发
WSL	连接 WSL 开发（Windows 用户）
Chinese (Simplified) Language Pack	中文界面（可选）

打开项目后按 F1，输入 Python: Select Interpreter，选择项目的 .venv 或 conda 环境。VS Code 左下角会显示当前使用的环境。

常见问题

现象	原因与解决
ModuleNotFoundError: No module named 'xxx'，但明明装过	装包和运行用的不是同一个环境。运行 which python 和 python -c "import sys; print(sys.executable)" 检查；VS Code 里检查左下角选中的解释器
error: externally-managed-environment	Ubuntu 24.04 等新系统禁止用 pip 往系统 Python 里装包。用 uv 或 conda 创建虚拟环境再装
pip install 很慢或超时	配置清华镜像，见上文
依赖冲突，装不上	新建一个干净的环境，按论文仓库要求的 Python 版本和依赖版本重新装
装 PyTorch 后 torch.cuda.is_available() 是 False	见 GPU 与 CUDA