Python uv 使用指南

目录

简介

uv 是 Astral 推出的新一代 Python 包管理工具，可以理解为：

pip + venv + poetry + pip-tools 的统一替代品（Rust 实现）

核心优势

• 安装速度极快（远超 pip）
• 原生虚拟环境管理（替代 venv）
• 现代依赖管理（pyproject.toml）
• 自动锁依赖（uv.lock）

本文档整理 uv 的安装、镜像源配置、标准工作流命令指南等内容。

1. 安装uv

Linux / macOS / WSL

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

Windows（PowerShell）

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

验证：

uv --version

2. 国内配置镜像源

uv 默认访问 PyPI，在国内环境可能慢或不稳定，这里配置下镜像源。

Linux / macOS / WSL

echo 'export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple' >> ~/.bashrc
source ~/.bashrc

# 如果使用zsh
echo 'export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell

setx UV_INDEX_URL "https://pypi.tuna.tsinghua.edu.cn/simple"

重新打开终端生效。

其它可选镜像源

3. 标准工作流

管理python:

uv python install 3.11
uv python install 3.13

查看版本：

uv python list

创建项目:

uv init my_project
cd my_project

创建虚拟环境:

uv venv

此时会生成.venv/。使用以下命令可以创建指定python版本的虚拟环境：

uv venv --python 3.11

安装依赖：

uv add fastapi uvicorn requests

会自动写入 pyproject.toml。不需要pip freeze，避免requirements.txt 混乱管理。

同步环境：

uv sync

运行项目：

uv run main.py

uv pip install -r requirements.txt