高性能 Python 包管理器 uv 的安装与使用

1 什么是 uv？

uv 是 Astral 公司推出的一款基于 Rust 编写的 Python 包管理工具，旨在成为“Python 的 Cargo”。它提供了快速、可靠且易用的包管理体验，在性能、兼容性和功能上都有出色表现，为 Python 项目的开发和管理带来了新的选择。

uv 的主要优势在于其速度快和功能全面。得益于 Rust 的性能优势，uv 在安装依赖等方面的速度远超其他工具。同时，uv 提供了一站式的服务，从安装 Python、管理虚拟环境，到安装和管理包，再到管理项目依赖，都能处理得很好。

2 安装 uv

在 macOS、Linux 和 Windows 上，可以通过以下方式安装 uv：

# 在 macOS 和 Linux 上安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 在 Windows 上：使用 Astral.sh 提供的安装脚本
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 在 Windows 上：使用 scoop 安装 uv
scoop install uv

# 在 MacOS 上：使用 Homebrew 安装 uv
brew install uv

# 假若已经安装了 python，也支持通过 pip 安装：
pip install uv

# 验证安装是否成功
uv --help

3 uv 基础使用

uv 具有与 npm、yarn、cargo 类似的使用体验，其效果与 Node.js 的 npm 以及 Rust 中的 cargo 非常相似，主要通过 pyproject.toml 和 uv.lock 两个文件实现对项目的包依赖管理。

• pyproject.toml：类似于 Node.js 项目中的 package.json 文件，用于定义项目包依赖。
• uv.lock：类似于 Node.js 项目中的 package-lock.json 和 yarn.lock 文件，用于锁定依赖版本。

3.1 使用 uv 创建、运行和管理项目示例

使用 uv 初始化创建项目

# 新建项目：这将创建一个包含默认文件和目录结构的项目。
# 项目结构通常包括 .venv（虚拟环境目录）、.python-version（指定 Python 版本的文件）、README.md（项目说明文件）、main.py（项目主文件）和 pyproject.toml（项目配置文件）等。
uv init myproject
cd myproject

# 或：在现有目录初始化
uv init

# 添加依赖
uv add requests

虚拟环境管理

# 创建默认 .venv
uv venv
# 指定路径
uv venv /path/to/venv
# 指定 Python 版本
uv venv --python 3.11
# 激活环境
source .venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows

依赖管理

# 添加一个依赖
uv add <package_name>
uv add "django>=4.2,<5.0"

# 安装开发依赖
uv add --dev pytest black

# 从 requirements.txt 安装
uv pip install -r requirements.txt

# 移除依赖
uv remove requests

# 更新依赖
uv update requests
uv update --all

# 安装所有依赖
uv install

依赖锁定与同步

# 生成/更新锁文件
uv lock
# 按锁文件精确安装
uv sync

运行项目

# 运行当前目录下的 main.py 文件
uv run ./main.py

# 运行 pyproject.toml 中定义的脚本
uv run start

# 运行已安装的 python 模块
uv run -m aktools

Python 版本管理

# 要查看可用和已安装的 Python 版本：
uv python list

# 安装最新的 Python 版本：
uv python install

# 或安装 Python 指定的版本，如 3.12
uv python install 3.12

# 使用指定版本运行脚本
uv run --python 3.11 myscript.py

典型工作流：

• uv init my-project 初始化项目
• uv add requests pandas 添加项目依赖
• 编写代码，运行项目 uv run -m pytest、uv lock
• 部署环境 uv sync

实战技巧与建议：

• 并行安装：uv 默认开启多线程下载，可通过 uv install --jobs=4 自定义线程数。
• 加速私有仓库依赖：默认使用 pip 配置源，也支持通过配置 UV_INDEX 环境变量指向自定义源。
• 避免全局污染：使用 --prefix 参数将依赖安装到项目目录。
• 兼容旧项目：可直接替换 pip install 为 uv install 进行迁移。
• 性能测试对比：在大型项目（如包含数百个依赖）中，uv 安装速度可提升 3-5倍。

3.2 设置使用国内镜像源

python 安装依赖包时，默认使用 pip 配置源，国内访问较慢。可设置为国内镜像源以加速依赖包的安装。

设置国内镜像源：

# 设置 pip 使用国内镜像源
uv pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 也可通过环境变量形式设置，如：
export UV_INDEX_URL="https://mirrors.aliyun.com/pypi/simple/"
export PIP_INDEX_URL="https://mirrors.aliyun.com/pypi/simple/"

python 常用国内镜像源列表：

• 阿里云: https://mirrors.aliyun.com/pypi/simple/
• 豆瓣: http://pypi.douban.com/simple/
• 网易: http://mirrors.163.com/pypi/simple/
• 腾讯: https://mirrors.cloud.tencent.com/pypi/simple/
• 清华大学: https://pypi.tuna.tsinghua.edu.cn/simple/
• 中国科学技术大学: http://pypi.mirrors.ustc.edu.cn/simple/

4 uv 与 pip/conda/virtualenv

总结：

• uv 适合追求极致速度与简洁体验的开发者，尤其适合频繁安装依赖或资源受限环境。
• pip 作为官方工具生态完善，但性能与隔离性较弱。
• conda 适合管理跨语言依赖与科学计算环境。
• virtualenv 专注环境隔离，但需额外配置。

5 扩展参考

uv 作为新一代包管理器，正在用“简单即高效”的理念重塑 Python 开发体验。无论是追求速度的全栈开发者，还是资源受限的嵌入式场景，它都值得一试。✨

• 官方文档
• uv中文文档
• UV GitHub 仓库
• 开始使用uv作为python的包管理器