UV使用指南

关键要点

• UV 是一个现代、高性能的 Python 包管理器，由 Rust 编写，速度比传统工具如 pip 快 10-100 倍。
• 它可以替代 pip、Poetry 和 virtualenv，提供项目管理和依赖解析功能。
• 安装方法包括官方脚本（适用于 macOS/Linux 和 Windows）或通过 pip/pipx。
• 使用 UV 可以初始化项目、添加依赖、管理虚拟环境，并支持多 Python 版本管理。
• 从 pip 或 Pipenv 迁移到 UV 相对简单，但可能需要额外的工具如 migrate-to-uv。

---

安装 UV

UV 的安装有多种方式，推荐使用官方安装脚本以确保最佳性能。以下是具体步骤：

使用官方安装脚本

• macOS 和 Linux：
  运行以下命令：

  curl -LsSf https://astral.sh/uv/install.sh | sh  
  

  如果遇到权限问题，可以使用 sudo：

  curl -LsSf https://astral.sh/uv/install.sh | sudo sh  
  

• Windows：
  在 PowerShell 中运行（需要管理员权限）：

  irm https://astral.sh/uv/install.ps1 | iex  
  

替代安装方法

• 通过 pip 安装（不推荐用于系统范围安装）：

  pip install uv  
  

• 通过 pipx 安装（适合工具式使用）：

  pipx install uv  
  

安装完成后，验证版本：

uv version  

例如，输出可能为 uv 0.4.25 (97eb6ab4a 2024-10-21)。

---

使用 UV 基础

UV 既可以作为 pip 的替代品，也支持项目管理。以下是两种主要使用方式：

作为 pip 的替代品

• 安装包：
  使用 uv pip install package_name，例如：

  uv pip install requests  
  

• 创建虚拟环境：
  使用 uv venv，例如：

  uv venv  
  

  这会创建虚拟环境，激活后可使用 source .venv/bin/activate（Unix）或 .venv\Scripts\activate（Windows）。

• 编译需求文件：
  从 requirements.in 生成 requirements.txt：

  uv pip compile requirements.in --output-file requirements.txt  
  

• 同步依赖：
  根据 requirements.txt 同步环境：

  uv pip sync requirements.txt  
  

项目管理

UV 提供更强大的项目管理功能，适合复杂项目：

• 初始化项目：
  创建新项目：

  uv init project_name  
  

  这会生成 .gitignore、.python-version、README.md 和 pyproject.toml 等文件，并自动初始化 Git。

• 添加依赖：
  添加包到项目：

  uv add package_name  
  

  这会更新 pyproject.toml 和 uv.lock，并在虚拟环境中安装包。移除依赖使用：

  uv remove package_name  
  

• 运行脚本：
  在项目环境中运行脚本：

  uv run script_name.py  
  

• 锁定和同步依赖：
  生成锁文件：

  uv lock  
  

  同步依赖：

  uv sync  
  

  锁文件确保可重复构建，建议提交到版本控制。

---

高级功能

UV 提供更多高级功能，适合复杂开发需求：

处理脚本

• 添加脚本并指定依赖：
  为脚本添加依赖：

  uv add --script script_name.py requests  
  

  这会更新脚本并记录依赖。

• 运行脚本：
  在隔离环境中运行：

  uv run script_name.py  
  

使用命令行工具

UV 支持运行工具，无需手动管理环境：

• 运行工具：

  uv tool run black script.py  
  

  或使用简写：

  uvx black script.py  
  

  这会在缓存中创建临时虚拟环境，运行后自动清理。

管理多个 Python 版本

UV 可以安装和管理不同 Python 版本：

• 安装版本：
  安装多个版本：

  uv python install 3.10 3.11 3.12  
  

• 设置项目 Python 版本：
  编辑 .python-version 文件，设置所需版本（如 3.11），然后运行：

  uv sync  
  

  列出已安装版本：

  uv python list --only-installed  
  

  如果遇到权限问题（macOS/Linux），修复：

  sudo chown -R $USER ~/.local/share/uv  
  

---

从其他包管理器迁移

迁移到 UV 相对简单，以下是常见场景：

从 pip 迁移

• 将 pip install 替换为 uv pip install，例如：

  uv pip install package_name  
  

• 如果有 requirements.txt，直接同步：

  uv pip sync requirements.txt  
  

• 虚拟环境创建从 python -m venv .venv 改为：

  uv venv  
  

从 Pipenv 迁移

可以使用 migrate-to-uv 工具简化迁移：

1. 安装工具：

   pipx install migrate-to-uv  
   

2. 在项目目录运行：

   migrate-to-uv  
   

   这会将 Pipfile 转换为 pyproject.toml，并设置 UV 项目结构。
   注意：CI 工作流可能需要调整，详情见 migrate-to-uv GitHub。

---

疑难解答

以下是一些常见问题及其解决方法：

常见问题

1. 权限错误

   • macOS/Linux：确保有足够权限，可能需要 sudo 安装脚本。
   • Windows：以管理员身份运行 PowerShell。

2. Python 版本未找到

   • 确保所需版本已安装，可用 uv python install version 安装。
   • 检查 PATH，确保 UV 能找到 Python。

3. 依赖解析失败

   • 检查包名和版本规范是否有误。

   • 尝试更新包索引：

     uv pip install -U  
     

寻求帮助

更多信息请参考官方文档 UV 文档 或访问 UV GitHub。

---

详细报告

以下是关于 UV Python 包管理器的全面使用指南，涵盖安装、使用、迁移和疑难解答的详细信息，旨在为用户提供专业且详尽的参考。

引言

UV 是一个由 Rust 编写的现代高性能 Python 包管理器，旨在替代传统工具如 pip、Poetry 和 virtualenv。它通过高效的架构和实现，解决了 Python 生态系统中常见的痛点，如安装缓慢、依赖冲突和环境管理复杂性。根据 DataCamp 教程，UV 的速度比传统工具快 10-100 倍，特别适合大型项目和频繁的依赖管理任务。

UV 的核心目标是提供一个统一的接口，类似于 Rust 的 Cargo，涵盖包安装、项目管理、脚本运行和多 Python 版本管理等功能。根据 Astral 博客，它最初于 2024 年 2 月发布，作为 pip 的替代品，后续扩展为端到端解决方案。

安装指南

安装 UV 有多种方法，推荐使用官方安装脚本以确保系统兼容性和性能。以下是详细步骤：

平台	方法	命令	备注
macOS/Linux	官方安装脚本	`curl -LsSf https://astral.sh/uv/install.sh	sh`
Windows	官方 PowerShell 脚本	`irm https://astral.sh/uv/install.ps1	iex`
所有平台	通过 pip 安装（不推荐系统范围）	pip install uv	适合虚拟环境
所有平台	通过 pipx 安装	pipx install uv	适合工具式使用

安装完成后，验证版本：

uv version  

例如，截至 2025 年 3 月 14 日，版本可能为 uv 0.4.25 (97eb6ab4a 2024-10-21)，具体取决于发布日期。

根据 Ubuntu Shell 指南，UV 不依赖 Python 本身，但需要 Python 环境来安装依赖，因此确保系统已安装 Python。

基础使用

UV 提供两种主要使用模式：作为 pip 的替代品和项目管理工具。以下是详细命令和示例：

作为 pip 的替代品

UV 的 pip 接口允许用户无缝迁移现有工作流。以下是常见命令：

• 安装包：

  uv pip install package_name  
  

  例如，安装 requests：

  uv pip install requests  
  

• 创建虚拟环境：

  uv venv  
  

  生成虚拟环境后，激活命令为 source .venv/bin/activate（Unix）或 .venv\Scripts\activate（Windows）。

• 编译需求文件：
  从 requirements.in 生成 requirements.txt：

  uv pip compile requirements.in --output-file requirements.txt  
  

  根据 官方文档，这支持平台无关解析（--universal）。

• 同步依赖：
  根据 requirements.txt 同步：

  uv pip sync requirements.txt  
  

  这比 pip 快得多，尤其在大型项目中。

项目管理

UV 的项目管理功能更适合复杂开发，基于 pyproject.toml 和锁文件 uv.lock。以下是关键命令：

• 初始化项目：

  uv init project_name  
  

  根据 DataCamp 教程，这会生成 .gitignore、.python-version、README.md 和 pyproject.toml，并自动初始化 Git。

• 添加依赖：

  uv add package_name  
  

  例如，添加 scikit-learn 和 xgboost：

  uv add scikit-learn xgboost  
  

  这会更新 pyproject.toml，例如添加 scikit-learn>=1.5.2，并在首次运行时创建虚拟环境，后续复用。移除依赖：

  uv remove package_name  
  

• 运行脚本：
  在项目环境中运行：

  uv run script_name.py  
  

  例如，运行 hello.py：

  uv run hello.py  
  

• 锁定和同步依赖：
  生成锁文件：

  uv lock  
  

  同步依赖：

  uv sync  
  

  锁文件确保可重复构建，建议提交到版本控制。导出为 requirements.txt：

  uv export -o requirements.txt  
  

高级功能

UV 提供更多高级功能，适合脚本开发、工具运行和多版本管理。

处理脚本

UV 支持为脚本管理依赖，无需传统虚拟环境激活：

• 添加脚本依赖：

  uv add --script script_name.py requests  
  

  这会更新脚本并记录依赖，例如为 example.py 添加 requests。

• 运行脚本：

  uv run script_name.py  
  

  根据 DataCamp 教程，这会在隔离环境中运行，安装依赖耗时仅 12ms（缓存热时）。

使用命令行工具

UV 支持运行工具，无需手动管理环境：

• 运行工具：

  uv tool run black script.py  
  

  或简写：

  uvx black script.py  
  

  根据 官方文档，这会在缓存中创建临时虚拟环境，运行后自动清理，适合如 black、ruff 等工具。安装工具：

  uv tool install ruff  
  

管理多个 Python 版本

UV 可以安装和管理不同 Python 版本，适合多版本开发：

• 安装版本：

  uv python install 3.10 3.11 3.12  
  

  例如，安装 3.10、3.11、3.12，耗时约 3.42 秒。

• 列出版本：

  uv python list --only-installed  
  

• 设置项目版本：
  编辑 .python-version 文件，例如设置为 3.11，然后运行：

  uv sync  
  

  如果需要特定版本运行命令：

  uv run --python [email protected] -- python  
  

  如果遇到权限问题（macOS/Linux）：

  sudo chown -R $USER ~/.local/share/uv  
  

从其他包管理器迁移

迁移到 UV 相对简单，以下是常见场景：

从 pip 迁移

• 将 pip install 替换为 uv pip install，例如：

  uv pip install package_name  
  

• 如果有 requirements.txt，直接同步：

  uv pip sync requirements.txt  
  

• 虚拟环境创建从 python -m venv .venv 改为：

  uv venv  
  

  根据 Stack Overflow 讨论，这适合简单项目。

从 Pipenv 迁移

Pipenv 用户可以利用 migrate-to-uv 工具：

• 安装工具：

  pipx install migrate-to-uv  
  

• 运行迁移：

  migrate-to-uv  
  

  根据 Medium 文章，这会将 Pipfile 转换为 pyproject.toml，并处理依赖版本。注意 CI 工作流可能需要调整，详情见 migrate-to-uv GitHub。

疑难解答

以下是一些常见问题及其解决方法：

常见问题

1. 权限错误

   • macOS/Linux：可能需要 sudo 安装脚本，例如：

     curl -LsSf https://astral.sh/uv/install.sh | sudo sh  
     

   • Windows：确保以管理员身份运行 PowerShell。

2. Python 版本未找到

   • 确保所需版本已安装，可用 uv python install version 安装。

   • 检查 PATH，确保 UV 能找到 Python。根据 DataCamp 教程，可能需要修复权限：

     sudo chown -R $USER ~/.local/share/uv  
     

3. 依赖解析失败

   • 检查包名和版本规范是否有误。

   • 尝试更新包索引：

     uv pip install -U  
     

寻求帮助

更多信息请参考官方文档 UV 文档 或访问 UV GitHub。

结论

UV 是一个高效的 Python 包管理器，适合从简单包安装到复杂项目管理的各种场景。通过本指南，用户可以轻松掌握 UV 的使用，提升开发效率。

关键引用

• UV 官方文档：全面使用指南
• DataCamp 教程：UV 快速入门
• Medium 文章：从 Pipenv 迁移到 UV
• UV GitHub 页面：项目和问题跟踪
• migrate-to-uv GitHub 项目：迁移工具
• Ubuntu Shell 指南：UV 安装步骤
• Stack Overflow 讨论：从简单项目迁移到 UV