当前位置：首页 > article >正文

Python uv包管理工具使用详解

article 2025/8/2 12:09:37

一、UV 工具概述

UV 是由 Astral 团队（Ruff 工具开发者）用 Rust 编写的新一代 Python 包管理器，旨在替代传统工具链（如 pip、virtualenv、poetry 等），提供以下核心优势

：

极速性能：依赖解析与安装速度比 pip 快 10-100 倍，尤其在大型项目中优势显著。
一体化功能：集成虚拟环境管理、依赖锁定、Python 版本控制、脚本执行等。
兼容性：支持 pyproject.toml 和 requirements.txt，无缝迁移现有项目。
跨平台：支持 Windows、macOS 和 Linux。

二、安装与配置

1. 安装 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
```

验证安装：uv --version

2. 配置环境变量

安装完成后，按提示将 UV 添加到系统 PATH（默认路径：~/.local/bin 或 $HOME/.cargo/bin）。

三、核心功能详解

1. 虚拟环境管理

创建虚拟环境：

uv venv  # 默认创建到当前目录的 .venv 文件夹#可以尝试uv venv .myvenv创建名为.myvenv目录的虚拟环境。但楼主遇到了问题，这个问题排查好久未解决，索性直接用.venv

遇到的问题如下，尝试很多方案未解决

支持指定 Python 版本：

uv venv --python 3.11  # 使用系统已安装的 Python
uv venv --python 3.13.0  # 自动下载并安装指定版本[5,13](@ref)

激活环境：

# macOS/Linux
source myenv/bin/activate
# Windows
myenv\Scripts\activate

2. 依赖管理

安装单个包（自动写入 pyproject.toml）：

uv add requests pandas  # 安装并记录核心依赖
uv add --dev pytest     # 开发依赖[5,13](@ref)

批量安装：

uv install -r requirements.txt  # 从文件安装
uv install .                    # 安装当前项目依赖[8,13](@ref)

依赖锁定：

uv lock               # 生成 uv.lock 文件
uv sync --locked      # 根据锁定文件安装依赖（CI/CD 推荐）[13](@ref)

升级/移除依赖：

uv sync --upgrade          # 更新所有依赖
uv sync --upgrade-package pandas  # 指定更新
uv remove requests         # 移除依赖[8,13](@ref)

3. 项目管理

初始化项目：

uv init myproject  # 生成 pyproject.toml 和 .venv

示例 pyproject.toml 配置：

[project]
name = "my_project"
version = "0.1.0"
dependencies = ["requests>=2.28"]
requires-python = ">=3.10"
[project.optional-dependencies]
dev = ["pytest", "black"][5,13](@ref)

4. 高级功能

脚本依赖注入：

uv add --script example.py requests  # 在脚本头部添加依赖声明
uv run example.py                   # 自动安装并运行[4,9](@ref)

工具管理（类似 pipx）：

uv tool install black         # 全局安装代码格式化工具
uvx black .                   # 在隔离环境中运行[4,9](@ref)

Python 版本管理：

uv python list               # 查看可用版本
uv python install 3.13       # 安装指定版本
uv python pin 3.13           # 设置项目默认版本[5,12](@ref)

四、最佳实践

1. 工作流推荐

初始化项目：

uv init myproject --python 3.11
cd myproject

添加依赖：

uv add fastapi uvicorn
uv add --dev pytest

同步环境：

uv sync  # 安装依赖并更新锁定文件

团队协作：
- 提交 pyproject.toml 和 uv.lock 到版本控制。
- 其他成员克隆后执行 uv sync --locked 即可复现环境。

2. 性能优化

并行安装：

uv install -j8  # 使用 8 线程加速[2,8](@ref)

离线模式：

uv install --offline  # 利用缓存安装[2](@ref)

五、与其他工具对比

功能	UV	pip	Poetry
安装速度	⚡ 极快（Rust 实现）	慢	中等
虚拟环境管理	✅ 内置	❌ 需配合 venv	✅ 内置
依赖锁定	✅ 自动生成 lock	❌ 需 pip-tools	✅ 支持
Python 版本控制	✅ 支持	❌	❌
脚本运行	✅ 原生支持	❌	❌