已有项目根据 `pyproject.toml` 使用 uv 创建虚拟环境

一、操作步骤

1. 进入项目目录

cd /path/to/existing_project

2. 创建虚拟环境

• 默认创建（使用项目中指定的 Python 版本）：

  uv venv  默认生成 .venv 目录
  

  • 若项目中存在 .python-version 文件（如内容为 3.12），uv 会自动使用该版本。
  • 若项目中没有 .python-version，但 pyproject.toml 中有 requires-python 字段（如 >=3.11），uv 会自动选择兼容版本。

• 指定 Python 版本：

  uv venv --python 3.12  强制使用 Python 3.12 创建环境
  

3. 同步依赖到虚拟环境

uv sync  根据 pyproject.toml 安装依赖并生成 uv.lock

• 参数说明：
  • --upgrade：升级所有依赖到最新版本。
  • --upgrade-package fastapi：仅升级指定包。

4. 激活虚拟环境

Linux/macOS
source .venv/bin/activate
Windows
.venv\Scripts\activate

二、核心原理与优势

1. 依赖解析：
   • uv 从 pyproject.toml 的 [project.dependencies] 字段读取依赖声明，并通过 uv.lock 锁定精确版本，确保环境一致性。
   • 支持 requirements.txt 迁移：若项目原有 requirements.txt，可通过 uv add -r requirements.txt 生成 pyproject.toml。
2. 虚拟环境轻量化：
   • 虚拟环境仅占用约 30MB 空间，比 conda 轻量 80%。
   • 使用全局缓存加速安装，避免重复下载。
3. 跨平台兼容性：
   • 自动适配不同操作系统的依赖树（如 Windows 和 Linux 的二进制包差异）。

三、常见场景与问题解决

1. 项目未指定 Python 版本

• 手动创建 .python-version 文件：

  echo "3.12" > .python-version  指定 Python 3.12
  uv venv  重新创建环境
  

2. 依赖冲突或版本不兼容

• 检查依赖树：

  uv tree  查看依赖关系树，定位冲突包
  

• 强制升级依赖：

  uv sync --upgrade  升级所有依赖
  uv lock --upgrade  重新生成 uv.lock
  

3. 虚拟环境未生效

• 验证 Python 路径：

  which python  应指向 .venv 目录（Linux/macOS）
  where python  应指向 .venv\Scripts 目录（Windows）
  

• 清理缓存：

  uv cache clean  清除无效缓存
  

四、对比传统工具

五、最佳实践

1. 提交 uv.lock：

   • 将 uv.lock 提交到版本控制（如 Git），确保团队环境一致。

2. 使用 uv run 替代手动激活：

   uv run python main.py  自动激活环境并运行
   

3. 定期更新依赖：

   uv lock --upgrade  每月更新一次依赖版本
   

   通过 uv，开发者可以高效管理已有项目的虚拟环境与依赖，实现从初始化到部署的全流程自动化。