【UV python包管理工具简单应用足够】

Python uv 使用指南（详细完整版）

一、uv 简介

uv 是由 Astral 团队开发的超高速 Python 包管理器与虚拟环境工具 ，基于 Rust 编写，核心优势是极快的安装速度（比 pip、poetry 快 10-100 倍）、零配置开箱即用，同时兼容 pip、requirements.txt、pyproject.toml 等生态，可无缝替代 pip、venv、pip-tools 等工具，兼顾速度与兼容性，适合个人开发、团队协作及生产环境。

核心特性：

极速解析与安装：依赖解析、包下载、缓存复用全链路优化，大型项目秒级完成；
内置虚拟环境：自动创建/激活虚拟环境，无需手动配置 venv；
全生态兼容：支持 requirements.txt、pyproject.toml、setup.py，可直接迁移现有项目；
内置缓存：全局缓存包文件，重复安装无需重新下载；
轻量无依赖：单二进制文件，无需 Python 环境即可安装，跨平台一致。

二、安装 uv

2.1 跨平台一键安装

支持 Windows、macOS、Linux，无需提前安装 Python，执行对应命令即可：

macOS/Linux

bash 复制代码

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

Windows（PowerShell）

powershell 复制代码

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

2.2 手动安装（可选）

从 uv GitHub Releases 下载对应系统的二进制文件，解压后添加到系统 PATH 即可。

2.3 验证安装

安装完成后，执行以下命令验证是否成功：

bash 复制代码

uv --version
# 输出示例：uv 0.2.0 (x86_64-apple-darwin)

三、基础使用：核心命令速览

3.1 初始化项目（自动配置虚拟环境）

进入项目目录，执行 uv init 自动生成项目结构、创建虚拟环境（默认 .venv）：

bash 复制代码

# 进入项目目录
cd my-python-project
# 初始化项目
uv init

初始化后生成的结构：

复制代码

my-python-project/
├── .venv/           # 自动创建的虚拟环境
├── pyproject.toml   # 项目配置文件（依赖、元数据）
└── README.md

pyproject.toml 核心配置（自动生成）：

toml 复制代码

[project]
name = "my-python-project"
version = "0.1.0"
dependencies = []  # 项目依赖在此添加

3.2 安装依赖

3.2.1 安装单个包

bash 复制代码

# 安装最新版
uv add requests
# 安装指定版本
uv add requests==2.31.0
# 安装版本范围
uv add "requests>=2.30.0,<3.0.0"
# 安装开发依赖（仅开发环境需要，如测试、格式化工具）
uv add --dev pytest black ruff

3.2.2 从 requirements.txt 安装

bash 复制代码

uv pip install -r requirements.txt

3.2.3 从 pyproject.toml 安装（全量依赖）

bash 复制代码

uv sync  # 自动安装 pyproject.toml 中的所有依赖（含开发依赖）
uv sync --no-dev  # 仅安装生产依赖

3.3 卸载依赖

bash 复制代码

# 卸载单个包
uv remove requests
# 卸载多个包
uv remove requests pytest
# 卸载开发依赖
uv remove --dev black

3.4 查看已安装依赖

bash 复制代码

uv show  # 查看当前项目所有依赖（含版本、来源）
uv show requests  # 查看单个包的详细信息（版本、依赖、路径）

3.5 运行 Python 代码

uv 可直接在虚拟环境中运行脚本/命令，无需手动激活虚拟环境：

bash 复制代码

# 运行 Python 脚本
uv run python main.py
# 运行依赖包的命令行工具（如 pytest、black）
uv run pytest tests/
uv run black .
# 进入虚拟环境的 Python 交互终端
uv run python

3.6 管理虚拟环境

3.6.1 手动创建虚拟环境

bash 复制代码

# 创建默认虚拟环境（.venv）
uv venv
# 创建指定名称的虚拟环境
uv venv my-env

3.6.2 激活虚拟环境

激活后可直接使用 python/pip 命令（等价于 uv 命令）：

bash 复制代码

# macOS/Linux
source .venv/bin/activate
# Windows（PowerShell）
.venv\Scripts\Activate.ps1
# Windows（CMD）
.venv\Scripts\activate.bat

3.6.3 删除虚拟环境

直接删除虚拟环境目录即可（如 .venv），或使用命令：

bash 复制代码

uv venv --remove  # 删除默认虚拟环境
uv venv --remove my-env  # 删除指定虚拟环境

四、进阶使用：场景化配置

4.1 锁定依赖版本（生成 uv.lock）

执行 uv lock 生成精确的依赖锁定文件，确保所有环境安装的依赖版本一致（类似 poetry.lock/Pipfile.lock）：

bash 复制代码

uv lock  # 生成/更新 uv.lock（基于 pyproject.toml）
uv sync  # 基于 uv.lock 安装精确版本（推荐团队协作使用）

uv.lock 包含所有依赖的精确版本、哈希值、依赖关系，提交到代码仓库可保证环境一致性。

4.2 配置镜像源（加速国内下载）

国内用户可配置 PyPI 镜像源，提升下载速度，支持两种方式：

4.2.1 临时使用（命令行参数）

bash 复制代码

uv add requests --index-url https://pypi.tuna.tsinghua.edu.cn/simple

4.2.2 永久配置（全局/项目级）

全局配置（所有项目生效）：

bash 复制代码

uv config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

项目级配置（仅当前项目生效）：
在 pyproject.toml 中添加：
toml 复制代码
```
[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
```

4.3 导出依赖文件

兼容传统 pip 生态，可将依赖导出为 requirements.txt：

bash 复制代码

# 导出生产依赖
uv export --format requirements.txt --output requirements.txt
# 导出全量依赖（含开发依赖）
uv export --format requirements.txt --dev --output requirements-dev.txt

4.4 缓存管理

uv 内置全局缓存，避免重复下载，可手动管理缓存：

bash 复制代码

uv cache clean  # 清理所有缓存
uv cache info   # 查看缓存大小、路径
uv cache prune  # 清理过期/无用缓存

4.5 多 Python 版本管理

uv 支持指定 Python 版本创建虚拟环境，需提前安装对应 Python 版本（可通过 pyenv、官方安装包）：

bash 复制代码

# 使用 Python 3.10 创建虚拟环境
uv venv --python 3.10
# 初始化项目时指定 Python 版本
uv init --python 3.11

五、与其他工具对比（优势总结）

工具	速度	虚拟环境	依赖锁定	配置复杂度	生态兼容
uv	极快	内置	支持	零配置	全兼容
pip + venv	慢	手动	不支持	低	全兼容
poetry	中	内置	支持	中	部分兼容
pip-tools	中	手动	支持	中	全兼容

核心优势：速度碾压同类工具，零配置上手，同时保留 pip 生态兼容性，无需学习新语法即可迁移。

六、常见问题与解决方案

6.1 安装包时报错"版本冲突"

bash 复制代码

# 强制重新解析依赖并安装
uv sync --reinstall
# 查看冲突原因
uv show 冲突包名

6.2 虚拟环境无法激活

Windows PowerShell 执行策略限制：
powershell 复制代码
```
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
```
路径含中文/特殊字符：将项目移至纯英文路径。

6.3 下载速度慢

配置国内镜像源（参考 4.2 节），或清理缓存后重试：

bash 复制代码

uv cache clean && uv add 包名

6.4 迁移现有项目到 uv

进入项目目录，执行 uv init 生成 pyproject.toml；
执行 uv pip install -r requirements.txt 安装现有依赖；
执行 uv lock 生成锁定文件，后续用 uv sync 维护。

七、生产环境最佳实践

提交 pyproject.toml 和 uv.lock 到代码仓库，保证环境一致；
生产环境使用 uv sync --no-dev 仅安装生产依赖，减少体积；
配置镜像源加速部署，避免网络问题；
定期清理缓存（uv cache prune），避免缓存占用过多空间；
用 uv run 运行生产脚本，确保依赖环境隔离。

八、最佳实践

创建环境

xxx 占位符，根据需要设置

python 复制代码

uv venv xxx --python 3.12 # 创建一个环境：xxx, 指定python版本
uv config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple # 设置加速源
source .xxx/bin/activate  # 激活环境
uv pip install -r requirements.txt # 最好用 uv pip 安装包，快！

uv lock # 生成精确的依赖锁定文件uv.lock
uv export --format requirements.txt --output requirements.txt # 导出生产依赖

.... # 其它的和往常一样运行
python main.py

【UV python包管理工具 简单应用足够】

Python uv 使用指南（详细完整版）

一、uv 简介

二、安装 uv

2.1 跨平台一键安装

macOS/Linux

Windows（PowerShell）

2.2 手动安装（可选）

2.3 验证安装

三、基础使用：核心命令速览

3.1 初始化项目（自动配置虚拟环境）

3.2 安装依赖

3.2.1 安装单个包

3.2.2 从 requirements.txt 安装

3.2.3 从 pyproject.toml 安装（全量依赖）

3.3 卸载依赖

3.4 查看已安装依赖

3.5 运行 Python 代码

3.6 管理虚拟环境

3.6.1 手动创建虚拟环境

3.6.2 激活虚拟环境

3.6.3 删除虚拟环境

四、进阶使用：场景化配置

4.1 锁定依赖版本（生成 uv.lock）

4.2 配置镜像源（加速国内下载）

4.2.1 临时使用（命令行参数）

4.2.2 永久配置（全局/项目级）

4.3 导出依赖文件

4.4 缓存管理

4.5 多 Python 版本管理

五、与其他工具对比（优势总结）

六、常见问题与解决方案

6.1 安装包时报错"版本冲突"

6.2 虚拟环境无法激活

6.3 下载速度慢

6.4 迁移现有项目到 uv

七、生产环境最佳实践

八、最佳实践

创建环境

【UV python包管理工具简单应用足够】