uv — Python 包与环境管理工具h1

uv 介绍h2

uv 是一个由 Astral 公司用 Rust 开发的高性能 Python 包管理工具，旨在提供比传统 pip 更快的包安装和依赖管理体验。

与传统的 Python 包管理工具相比，uv 具有以下显著优势：

• 🚀 一体化工具：一个工具替代 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等多种工具
• ⚡️ 极致速度：比 pip 快 10-100 倍
• 🗂️ 全面项目管理：提供通用锁文件的综合项目管理功能
• ❇️ 脚本运行：支持带有内联依赖元数据的脚本运行
• 🐍 Python版本管理：安装和管理不同的 Python 版本
• 💾 高效磁盘空间利用：通过全局缓存实现依赖去重
• ⏬ 简易安装：无需 Rust 或 Python 环境，可通过 curl 或 pip 直接安装
• 🖥️ 多平台支持：支持 macOS、Linux 和 Windows 系统

uv 安装h2

使用官方安装脚本（推荐）h3

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

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

使用包管理器h3

Homebrewh4

# macOS (Homebrew)
brew install uv

WinGeth4

winget install --id=astral-sh.uv  -e

Scooph4

scoop install main/uv

PyPIh4

pip install uv

安装完成后，可以通过以下命令验证安装是否成功：

uv --version

uv 安装 Pythonh2

如果系统中已安装 Python，uv 会自动检测并使用，无需额外配置。不过，uv 也能够安装和管理 Python 版本。同时 uv 会根据需要自动安装缺失的 Python 版本，因此你无需预先安装 Python 即可上手。

安装最新版本的 Python：

uv python install

安装特定版本的 Python：

uv python install 3.12

安装多个 Python 版本：

uv python install 3.11 3.12

uv 运行 Python 项目h2

uv 使用 pyproject.toml 文件进行项目管理，这是现代 Python 项目的标准配置文件。

初始化项目h3

项目根目录下运行以下命令：

uv init --project .

这会创建基本的项目结构和 pyproject.toml 文件，并根据项目结构自动填充一些基本信息。

初始化虚拟环境h3

uv venv        # 在当前目录创建虚拟环境
uv venv .venv  # 在指定目录创建虚拟环境

激活虚拟环境h3

# Linux/macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

添加依赖h3

使用 uv add 命令可以向项目添加依赖。该命令会自动更新 pyproject.toml 文件、锁文件和项目环境：

# 添加单个包
uv add requests

# 指定版本约束
uv add 'requests==2.31.0'

# 添加 Git 依赖
uv add git+https://github.com/psf/requests

# 从 requirements.txt 文件添加所有依赖
uv add -r requirements.txt

卸载依赖h3

使用 uv remove 命令可以删除项目依赖：

uv remove requests

升级依赖h3

使用 uv lock 命令配合 --upgrade-package 参数可以升级指定包：

# 升级特定包
uv lock --upgrade-package requests

运行项目命令h3

uv run 命令可以在项目环境中运行脚本或命令。在每次运行前，UV 会验证锁文件是否与 pyproject.toml 同步，并确保环境与锁文件一致：

# 运行 Python 脚本
uv run main.py

迁移现有的 Python 项目到 uvh3

初始化 pyproject.tomlh4

使用 uv init 命令的 --bare 选项将仅创建 pyproject.toml，禁止创建额外文件，如 README.md、src/ 目录树、.python-version 文件等。

uv init --bare

添加项目依赖h4

1. 如果项目中存在 requirements.txt 文件，可以使用以下命令安装所有依赖，并同步添加到pyproject.toml文件中：

   uv add -r requirements.txt

   uv 会自动解析 requirements.txt 文件，并将其中的依赖添加到 pyproject.toml 的 dependencies 部分。

2. 如果项目中存在 pyproject.toml 文件，可以使用以下命令使用现有的 pyproject.toml：

   uv sync

uv 设置国内镜像源h2

uv 支持在项目、全局使用配置文件。

uv 会读取以下位置的配置文件（按优先级从高到低）：

• UV_CONFIG_FILE 环境变量指定的文件
• ./uv.toml
• ~/.uv/uv.toml
• ~/.config/uv/uv.toml

全局配置：h4

• Linux & MacOS：

  mkdir ~/.config/uv && vim ~/.config/uv/uv.toml

• Windows：

  %APPDATA%\uv\uv.toml

• 在该文件中添加以下内容：

  [[index]]
  url = "https://pypi.tuna.tsinghua.edu.cn/simple"
  default = true

项目配置：h4

• **文件路径：**项目目录下的 pyproject.toml

• 在该文件中添加以下内容：

[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

常用国内镜像源h4

• 清华大学：https://pypi.tuna.tsinghua.edu.cn/simple
• 阿里云：https://mirrors.aliyun.com/pypi/simple/
• 腾讯云：https://mirrors.cloud.tencent.com/pypi/simple
• 华为云：https://repo.huaweicloud.com/repository/pypi/simple