从 Conda 到 uv：现代化 Python 开发迁移指南

1. 核心思维转变 (Mental Model Shift)

在使用 uv 之前，你需要调整对“环境管理”的理解。

2. 命令对照速查表 (Cheat Sheet)

这是你最需要的部分，建议保存。

基础操作

包管理 (在项目内)

环境复现与同步

3. 详细工作流指南

放弃 Conda 后，你的工作流将分为两种场景：完整的项目开发 和 临时脚本/工具使用。

场景 A：完整的项目开发 (Project Workflow)

适用于：开发一个应用、数据分析项目、或者库。

1. 初始化项目：

   mkdir my-project
   cd my-project
   uv init  # 创建 pyproject.toml
   

   此时你可以固定 Python 版本：uv python pin 3.10

2. 添加依赖：

   不要手动 pip install，使用 add 命令。

   uv add pandas matplotlib scikit-learn
   

   uv 会自动创建虚拟环境 (.venv)，安装包，并锁定版本到 uv.lock。

3. 运行代码：

   你不需要激活环境！直接用 uv run。

   uv run main.py
   

   uv 会自动检测 .venv 中的环境并使用它。如果你想进入命令行交互，可以 uv run python。

4. 团队协作/部署：

   当你把代码传到服务器或给同事，只要传输 pyproject.toml 和 uv.lock。

   接收方只需运行：

   uv sync
   

   环境瞬间完美复刻。

场景 B：单脚本与临时任务 (Script Workflow)

适用于：跑一个网上的脚本，或者测试一个 demo。

Conda 用户经常为了跑一个脚本就创建一个环境，或者把 base 环境搞得很脏。uv 解决了这个问题。

1. 创建一个脚本文件 analysis.py

2. 直接运行并声明依赖：

   uv run --with "requests,pandas" analysis.py
   

   uv 会创建一个临时的隔离环境，安装 requests 和 pandas，跑完脚本后，你可以选择忽略这个环境，你的系统非常干净。

3. 脚本内声明 (Inline Metadata)：

   你甚至可以在 python 脚本头部写依赖：

   # /// script
   # dependencies = ["requests<3", "rich"]
   # ///
   import requests
   from rich import print
   print(requests.get("https://httpbin.org/json").json())
   

   然后直接运行 uv run analysis.py，uv 会自动读取注释去安装依赖。

场景 C：全局工具 (Tools)

适用于：Jupyter, Black, Ruff, Pyright 等命令行工具。

不要把这些工具装在项目环境里，也不要装在全局 Python 里。

# 安装并运行 Jupyter
uvx jupyter lab

# 使用 Ruff 格式化
uvx ruff check .

uvx 类似于 pipx，甚至不需要你显式安装，用完即走（或缓存）。

4. 常见问题与“坑” (FAQ)

Q1: Conda 安装的那些非 Python 库怎么办？（如 CUDA, ffmpeg, graphviz）

这是 Conda 唯一的护城河。

• uv 的策略： uv 专注 Python 包 (PyPI)。
• 解决方案：
  • 对于 CUDA/PyTorch：uv 支持完美安装 PyTorch（它会从 PyPI 拉取包含 CUDA 的 wheel 包）。命令：uv add torch 即可，现在的 PyPI wheel 包已经做得很好。
  • 对于 ffmpeg/graphviz：建议使用系统包管理器（apt, brew, choco）安装，或者使用 Docker。
  • 如果你的工作流极度依赖旧版二进制库的自动配置，保留 Miniconda 作为备用是合理的，但 95% 的场景可以迁移。

Q2: 我习惯了 activate，不想每次都打 uv run。

完全没问题。

source .venv/bin/activate
python main.py

这和标准 venv 一模一样。uv 只是帮你更快地创建了它。

Q3: 如何清理缓存？

uv 极其节省空间（使用硬链接），但如果你想清空：

uv cache clean

5. 极速迁移实战

如果你手头有一个 Conda 的 requirements.txt：

1. 创建一个新目录：mkdir migration_test && cd migration_test

2. 初始化 uv：uv init

3. 导入旧依赖：

   uv pip install -r requirements.txt
   

   (注意：这会把包安装进环境，但不会自动更新 pyproject.toml。建议手动用 uv add 重新整理一次依赖，以享受长期管理的红利)

你的下一步

建议你现在就在终端里敲下这行命令，体验一下什么叫“快到离谱”：

uv run --with "numpy,pandas" python -c "import pandas; print('Environment created and Pandas loaded!')"

如果这个指令成功了，你就已经迈出了放弃 Conda 的第一步。