需要快速管理 Python 依赖、虚拟环境和 Python…

在 Python 项目中快速安装/解析依赖、创建虚拟环境、管理 Python 版本，或从 pip/pip-tools/poetry 迁移并优化 CI/CD、Docker、monorepo 工作流时适用。

适用场景

解决思路

1. 安装 uv（macOS/Linux）：运行 `curl -LsSf https://astral.sh/uv/install.sh | sh`。
2. 安装 uv（Windows PowerShell）：运行 `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`。
3. 已安装 Python 时用 pip 安装 uv：`pip install uv`。
4. macOS 用 Homebrew 安装 uv：`brew install uv`。
5. 已有 Rust 时用 cargo 从 git 安装 uv：`cargo install --git https://github.com/astral-sh/uv uv`。
6. 验证安装：运行 `uv --version`，应输出 `uv 0.x.x`。
7. 创建新项目并进入：运行 `uv init my-project`，然后 `cd my-project`。
8. 在当前目录初始化项目：运行 `uv init .`。
9. 初始化会生成 `.python-version`（Python 版本）、`pyproject.toml`（项目配置）、`README.md`、`.gitignore`。
10. 安装包并在需要时创建 venv：运行 `uv add requests pandas`。
11. 安装开发依赖：运行 `uv add --dev pytest black ruff`。
12. 从 requirements.txt 安装：运行 `uv pip install -r requirements.txt`。
13. 从 pyproject.toml 同步安装：运行 `uv sync`。
14. 创建虚拟环境：运行 `uv venv`。
15. 指定 Python 版本创建虚拟环境：运行 `uv venv --python 3.12`。
16. 自定义名称创建虚拟环境：运行 `uv venv my-env`。
17. 使用系统 site packages 创建虚拟环境：运行 `uv venv --system-site-packages`。
18. 指定虚拟环境位置：运行 `uv venv /path/to/venv`。
19. Linux/macOS 激活虚拟环境：运行 `source .venv/bin/activate`。
20. Windows Command Prompt 激活虚拟环境：运行 `.venv\Scripts\activate.bat`。
21. Windows PowerShell 激活虚拟环境：运行 `.venv\Scripts\Activate.ps1`。
22. 不激活直接运行 Python 脚本：运行 `uv run python script.py`。
23. 不激活直接运行已安装 CLI 工具：运行 `uv run black .` 或 `uv run pytest`。
24. 用指定 Python 版本运行：运行 `uv run --python 3.11 python script.py`。
25. 向脚本传递参数：运行 `uv run python script.py --arg value`。
26. 添加依赖到 pyproject.toml：运行 `uv add requests`。
27. 添加带版本约束的依赖：运行 `uv add "django>=4.0,<5.0"`。
28. 添加多个包：运行 `uv add numpy pandas matplotlib`。
29. 添加开发依赖：运行 `uv add --dev pytest pytest-cov`。
30. 添加可选依赖组：运行 `uv add --optional docs sphinx`。
31. 从 git 添加依赖：运行 `uv add git+https://github.com/user/repo.git`。
32. 从 git 指定 ref 添加依赖：运行 `uv add git+https://github.com/user/repo.git@v1.0.0`。
33. 从本地路径添加依赖：运行 `uv add ./local-package`。
34. 以可编辑模式添加本地依赖：运行 `uv add -e ./local-package`。
35. 删除依赖：运行 `uv remove requests`。
36. 删除开发依赖：运行 `uv remove --dev pytest`。
37. 删除多个包：运行 `uv remove numpy pandas matplotlib`。
38. 升级指定包：运行 `uv add --upgrade requests`。
39. 升级所有包：运行 `uv sync --upgrade`。
40. 将包升级到最新：运行 `uv add --upgrade requests`。
41. 查看哪些包可升级：运行 `uv tree --outdated`。
42. 生成 uv.lock 文件：运行 `uv lock`。
43. 更新锁文件：运行 `uv lock --upgrade`。
44. 只锁定不安装：运行 `uv lock --no-install`。
45. 锁定并升级指定包：运行 `uv lock --upgrade-package requests`。
46. 安装 Python 版本：运行 `uv python install 3.12`。
47. 安装多个 Python 版本：运行 `uv python install 3.11 3.12 3.13`。
48. 安装最新 Python 版本：运行 `uv python install`。
49. 列出已安装 Python 版本：运行 `uv python list`。
50. 查找可用 Python 版本：运行 `uv python list --all-versions`。
51. 为项目固定 Python 版本：运行 `uv python pin 3.12`，会创建/更新 `.python-version` 文件。
52. 为命令指定 Python 版本：运行 `uv --python 3.11 run python script.py`。
53. 用指定版本创建 venv：运行 `uv venv --python 3.12`。
54. 在 pyproject.toml 的 [project] 中配置 name、version、description、readme、requires-python，并在 dependencies 中配置 `requests>=2.31.0`、`pydantic>=2.0.0`、`click>=8.1.0`。
55. 在 [project.optional-dependencies] 中配置 dev：`pytest>=7.4.0`、`pytest-cov>=4.1.0`、`black>=23.0.0`、`ruff>=0.1.0`、`mypy>=1.5.0`。
56. 在 [project.optional-dependencies] 中配置 docs：`sphinx>=7.0.0`、`sphinx-rtd-theme>=1.3.0`。
57. 在 [build-system] 中配置 `requires = ["hatchling"]` 和 `build-backend = "hatchling.build"`。
58. 在 [tool.uv] 中配置 dev-dependencies（由 uv 管理的额外开发依赖）。
59. 在 [tool.uv.sources] 中配置自定义包源，例如 `my-package = { git = "https://github.com/user/repo.git" }`。
60. 从 requirements.txt 迁移：运行 `uv add -r requirements.txt`。
61. 从 poetry 迁移：已有 pyproject.toml 时直接运行 `uv sync`。
62. 导出到 requirements.txt：运行 `uv pip freeze > requirements.txt`。
63. 导出带哈希的 requirements.txt：运行 `uv pip freeze --require-hashes > requirements.txt`。
64. 需要高级工作流时查看 `references/advanced-patterns.md`，覆盖 Docker 集成、锁文件管理、性能优化、工具比较、常见工作流、工具集成、故障排除、最佳实践、迁移指南和命令参考。

适用边界 · 注意事项

• 需要管理非 Python 依赖（例如 conda 提供的 C/C++ 库或系统二进制依赖）时，uv 不作为通用系统包管理器使用。
• 在无法安装或执行 uv 的环境（无网络、权限受限、必须完全离线）中，无法使用这些做法。
• 团队已标准化 pip/poetry/conda 且无迁移或提速需求时，引入 uv 的收益有限。