跳至内容
新生指南
开发环境配置
Python 环境配置

Python 环境配置

Python 项目的环境管理是科研编程中绕不开的基本功。不同的项目可能依赖不同版本的包，如果所有项目共享同一个全局环境，很快就会陷入"装了 A 的依赖，B 就跑不了"的困境。虚拟环境就是为了解决这个问题——每个项目拥有独立的 Python 环境和依赖包，互不干扰。

Python 版本选择

建议使用 Python 3.10 — 3.12。这个范围兼顾了最新的语言特性和第三方库的兼容性：

  • 3.12：最新稳定版，性能提升明显，大部分库已支持
  • 3.11：广泛兼容，推荐作为默认版本
  • 3.10：部分老项目可能指定此版本

可以通过以下命令检查当前 Python 版本：

terminal
python3 --version

如果需要管理多个 Python 版本（比如一个项目用 3.10，另一个用 3.12），推荐使用 uv（见下文），它内置了 Python 版本管理功能。

包管理工具对比

工具定位速度虚拟环境Python 版本管理推荐场景
uv现代一体化工具⚡ 极快✅ 内置✅ 内置新项目首选
pip + venvPython 标准工具一般✅ 内置❌教程示例、兼容性
conda科学计算环境管理较慢✅ 内置✅ 内置CUDA / 系统级依赖

建议：新项目优先使用 uv，因为它速度快、功能全、体验好。遇到旧项目或教程使用 pip 的情况时，pip + venv 的知识也必不可少。需要管理 CUDA 等系统级依赖时再考虑 conda。

uv：推荐的现代方案

uv 是 Astral 公司（Ruff 的开发者）推出的 Python 包管理和项目管理工具，用 Rust 编写，速度比 pip 快 10-100 倍。它集成了虚拟环境管理、Python 版本管理、依赖解析和锁文件等功能。

安装 uv

macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装后验证：

terminal
uv --version

创建项目

terminal
# 初始化一个新项目
uv init my-project
cd my-project

# 项目结构
# my-project/
# ├── .python-version    # 指定 Python 版本
# ├── pyproject.toml     # 项目配置和依赖声明
# ├── README.md
# └── src/
#     └── my_project/
#         └── __init__.py

uv init 会自动创建项目结构、虚拟环境和配置文件。pyproject.toml 是项目的核心配置，记录了依赖信息。

管理依赖

terminal
# 添加依赖（自动安装到虚拟环境）
uv add numpy pandas matplotlib

# 添加开发依赖（仅开发时需要，如测试工具）
uv add --dev pytest

# 移除依赖
uv remove pandas

# 同步环境（根据 pyproject.toml 安装所有依赖）
uv sync

uv add 会自动将包添加到 pyproject.toml 的依赖列表中，并生成 uv.lock 锁文件来记录精确的版本信息。这意味着其他人克隆你的项目后，只需运行 uv sync 就能得到完全一致的环境。

运行脚本

terminal
# 在项目的虚拟环境中运行 Python 脚本
uv run python main.py

# 运行模块
uv run python -m pytest

# 启动 Jupyter notebook
uv run jupyter notebook

uv run 会自动激活项目的虚拟环境来执行命令，不需要手动 source .venv/bin/activate。

管理 Python 版本

terminal
# 安装指定版本的 Python
uv python install 3.12

# 查看已安装的 Python 版本
uv python list

# 为当前项目固定 Python 版本
uv python pin 3.11

pip + venv：传统标准方案

pip 是 Python 自带的包管理器，venv 是自带的虚拟环境工具。虽然功能不如 uv 全面，但它们是 Python 的标准组成部分，不需要额外安装，而且几乎所有教程和文档都以 pip 为例。

创建虚拟环境

terminal
# 在项目目录下创建虚拟环境
python3 -m venv .venv

# 激活虚拟环境
# macOS / Linux:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

# 激活后，终端提示符会显示 (.venv) 前缀
# (.venv) $

安装包

terminal
# 激活虚拟环境后，用 pip 安装包
pip install numpy pandas matplotlib scikit-learn

# 安装指定版本
pip install torch==2.1.0

# 从 requirements.txt 安装所有依赖
pip install -r requirements.txt

导出和共享依赖

terminal
# 导出当前环境的所有包到 requirements.txt
pip freeze > requirements.txt

# 其他人可以用这个文件复现环境
pip install -r requirements.txt

退出虚拟环境

terminal
deactivate

Warning

记住：每次开始工作前都要激活虚拟环境。如果发现 pip install 安装的包找不到，多半是忘了激活。使用 uv 则不需要手动激活——uv run 会自动处理。

conda：科学计算方案

conda 是 Anaconda 生态中的环境和包管理工具。它的独特优势在于可以管理非 Python 依赖（如 CUDA 工具包、C/C++ 库等），这在深度学习环境配置中有时很有用。

推荐安装轻量版的 Miniconda 而非完整的 Anaconda（后者捆绑了大量可能用不到的包）。

基本操作

terminal
# 创建环境
conda create -n myproject python=3.11

# 激活环境
conda activate myproject

# 安装包（优先用 conda 安装，找不到再用 pip）
conda install numpy pandas scikit-learn
pip install axisfuzzy  # conda 没有的包用 pip

# 查看所有环境
conda env list

# 退出环境
conda deactivate

# 导出环境配置
conda env export > environment.yml

# 从配置文件创建环境
conda env create -f environment.yml

Tip

如果你使用 PyTorch 并且需要 GPU 加速，conda 安装 PyTorch + CUDA 通常比 pip 更省心。参见 PyTorch 官方安装指南。

推荐的项目结构

无论使用哪种工具，保持一致的项目结构会大大提高代码的可维护性：

my-research-project/
├── .venv/              # 虚拟环境（不要提交到 Git）
├── .gitignore          # Git 忽略规则
├── pyproject.toml      # 项目配置（uv 项目）
├── requirements.txt    # 依赖清单（pip 项目）
├── README.md           # 项目说明
├── data/               # 数据文件（通常不提交到 Git）
├── notebooks/          # Jupyter notebook
├── src/                # 源代码
│   └── main.py
├── tests/              # 测试代码
└── results/            # 实验结果

Note

.venv/ 和 data/ 目录通常不应提交到 Git 仓库。在 .gitignore 文件中添加以下内容：

.venv/
data/
__pycache__/
*.pyc

日常工作流总结 

# 新项目
uv init my-project && cd my-project
uv add numpy pandas matplotlib

# 日常开发
uv run python main.py
uv add some-new-package

# 共享给他人
# 对方只需：git clone + uv sync