Python 包管理工具推荐：uv

目录

简介

uv 是由 Astral 开发的超快速 Python 包管理器和项目管理工具，使用 Rust 编写，速度比 pip 快 10-100 倍。它不仅可以管理包依赖，还能管理多个 Python 版本和虚拟环境。

核心特性

  • 极速安装：Rust 编写，包安装速度极快
  • 多版本管理：轻松管理和切换不同 Python 版本
  • 统一工具：集成包管理、环境管理、版本管理于一体
  • 跨平台支持：完美支持 Linux、macOS、Windows 和 WSL

安装 uv

Linux / macOS / WSL

# 推荐方式
curl -LsSf [https://astral.sh/uv/install.sh](https://astral.sh/uv/install.sh) | sh

# 或通过 pip
pip install uv

Windows

powershell -c "irm [https://astral.sh/uv/install.ps1](https://astral.sh/uv/install.ps1) | iex"

Python 版本管理

安装和管理 Python 版本

# 安装特定版本
uv python install 3.11
uv python install 3.12
uv python install 3.13

# 查看已安装版本
uv python list

# 查看可用版本
uv python list --all-versions

# 设置项目默认版本
uv python pin 3.12

项目环境管理

为新项目创建环境

# 创建新项目
uv init myproject --python 3.11
cd myproject

# 创建虚拟环境
uv venv

# 添加依赖
uv add requests pandas numpy

为已有代码创建环境

# 在现有项目目录下
cd your_existing_project

# 初始化 uv 项目（不会覆盖已有文件）
uv init

# 创建虚拟环境
uv venv

# 添加已知的依赖
uv add openai pandas numpy

依赖管理

添加依赖

# 添加运行时依赖
uv add package-name

# 添加指定版本
uv add "openai==1.12.0"
uv add "pandas>=2.0.0"

# 添加开发依赖
uv add --dev pytest black ruff

# 添加可选依赖组
uv add --optional docs sphinx

更新依赖

由于 uv 使用 uv.lock 文件，直接运行 uv sync 不会更新已锁定的版本。如需更新，请使用以下命令：

1. 更新特定包
将某个包更新到 pyproject.toml 允许的最高版本：

uv lock --upgrade-package <package_name>
# 或者更新并同步环境
uv sync --upgrade-package <package_name>

2. 全量更新
更新所有依赖到最新兼容版本并同步环境：

uv sync --upgrade

3. 更改版本限制
如果你需要升级到一个超出当前 pyproject.toml 限制的版本（例如从 v1 升级到 v2）：

uv add "package_name>=2.0.0"

从已有依赖文件迁移

从 requirements.txt 导入

# 方法 1：一次性导入到 pyproject.toml
cat requirements.txt | grep -v "^#" | grep -v "^$" | xargs uv add

# 方法 2：只安装到环境（不修改 pyproject.toml）
uv pip install -r requirements.txt

使用已有 pyproject.toml

# 自动读取并同步依赖
uv sync

运行代码

使用 uv run（推荐）

# 运行 Python 脚本
uv run python script.py

# 运行模块
uv run python -m pytest

传统方式（激活环境）

# 激活虚拟环境
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate      # Windows

常用工作流

场景 1：开始新项目

uv init my-app --python 3.12
cd my-app
uv add fastapi uvicorn
uv run python main.py

在 WSL 中使用 uv

uv 在 WSL 环境中表现优异，与原生 Linux 体验一致。

常用命令速查

项目管理

命令 说明
uv init 初始化项目
uv sync 根据 lock 文件同步环境
uv run <cmd> 在虚拟环境中运行命令
uv self update 更新 uv 工具自身

依赖管理

命令 说明
uv add <pkg> 添加依赖
uv remove <pkg> 移除依赖
uv sync --upgrade 全量更新所有依赖
uv sync --upgrade-package <pkg> 更新指定依赖
uv pip list 查看已安装包

Python 版本

命令 说明
uv python install <ver> 安装指定 Python
uv python pin <ver> 固定当前项目 Python 版本

项目结构

my-project/
├── .venv/              # 虚拟环境
├── pyproject.toml      # 依赖声明
├── uv.lock             # 版本锁定文件
└── src/                # 源码

Git 版本控制

应该提交的文件

✅ pyproject.toml, uv.lock, .python-version

应该忽略的文件

❌ .venv/, __pycache__/, .ruff_cache/

为什么要提交 uv.lock？

  1. 环境一致性：确保全团队使用完全相同的版本。
  2. 可重现性：CI/CD 环境与开发环境 100% 一致。

最佳实践

  1. **始终使用 uv run**。
  2. **提交 uv.lock**。
  3. 定期维护：使用 uv sync --upgrade 保持依赖安全且最新。

迁移指南

从 pip 迁移：cat requirements.txt | xargs uv add。

故障排查

  • 安装失败：尝试 uv cache clean 后重新 uv sync。
  • 版本冲突：检查 pyproject.toml 中的版本限制是否过于严格。

总结

uv 是目前最快、最现代化的 Python 项目管理工具，强烈建议在生产环境和个人项目中使用。

参考资源

posted @ 2025-10-22 02:32  LexLuc  阅读(441)  评论(0)    收藏  举报