Python uv 完整使用指南

🚀 面向前端开发者的 Python 包管理工具 uv 详细教程
本文档将帮助前端开发者快速理解和使用 Python 的现代化包管理工具 uv

📖 目录

1. uv 简介与背景
2. 前端开发者友好的类比
3. 安装与环境配置
4. 基础使用教程
5. 实际项目迁移指南
6. 最佳实践
7. 常见问题与解决方案
8. 高级功能
9. 实战案例

1. uv 简介与背景

1.1 什么是 uv？

uv 是由 Astral 公司开发的极快的 Python 包管理器和项目管理工具，使用 Rust 编写。它被设计为 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等多个 Python 工具的统一替代品。

1.2 为什么选择 uv？

🚀 极致性能

比传统的 pip 快 10-100 倍
使用 Rust 编写，具有出色的性能
并行下载和安装包

🔧 统一工具链

包管理（替代 pip）
虚拟环境管理（替代 virtualenv、venv）
项目管理（替代 poetry）
Python 版本管理（替代 pyenv）
脚本运行（替代 pipx）

🎯 现代化设计

支持现代 Python 项目标准
与现有的 Python 生态系统完全兼容
自动生成锁文件确保依赖版本一致性

1.3 uv vs 传统工具对比

功能	传统工具	uv	优势
包安装	`pip install`	`uv add`	速度快 10-100 倍
虚拟环境	`python -m venv`	`uv venv`	自动管理，无需手动激活
依赖锁定	`pip-tools`	`uv lock`	内置功能，智能解析
项目管理	`poetry/pipenv`	`uv init/sync`	一体化解决方案
Python 版本	`pyenv`	`uv python`	统一管理
脚本运行	`pipx`	`uv run`	无需全局安装

2. 前端开发者友好的类比

2.1 概念映射表

Python 概念	前端对应概念	说明
虚拟环境 (venv)	`node_modules`	项目独立的依赖环境
requirements.txt	`package.json`	依赖列表文件
uv.lock	`package-lock.json`	锁定具体版本
pyproject.toml	`package.json` + 配置	项目配置文件
pip	`npm`	包管理器
pyenv	`nvm`	版本管理器

2.2 工作流对比

前端项目工作流

bash

# 1. 克隆项目
git clone project-name
cd project-name

# 2. 安装依赖
npm install

# 3. 启动开发服务器
npm run dev

# 4. 添加新依赖
npm install express

# 5. 运行脚本
npm run build

Python 项目工作流（uv 方式）

bash

# 1. 克隆项目
git clone project-name
cd project-name

# 2. 安装依赖
uv sync

# 3. 启动应用
uv run python app.py

# 4. 添加新依赖
uv add fastapi

# 5. 运行脚本
uv run pytest

Python 项目工作流（传统方式）

bash

# 1. 克隆项目
git clone project-name
cd project-name

# 2. 设置 Python 版本
pyenv local 3.11.0

# 3. 创建虚拟环境
python -m venv venv

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

# 5. 安装依赖
pip install -r requirements.txt

# 6. 启动应用
python app.py

可以看出，uv 的工作流程与前端工具非常相似，学习成本很低！

3. 安装与环境配置

3.1 安装 uv

Windows 安装

powershell

# 方法1：使用官方安装脚本（推荐）
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 方法2：使用 pip 安装
pip install uv

# 方法3：使用 winget
winget install --id=astral-sh.uv -e

# 方法4：使用 scoop
scoop install uv

macOS 安装

bash

# 方法1：使用官方安装脚本（推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 方法2：使用 Homebrew
brew install uv

# 方法3：使用 pip
pip install uv

Linux 安装

bash

# 方法1：使用官方安装脚本（推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 方法2：使用 pip
pip install uv

3.2 验证安装

bash

# 检查版本
uv --version

# 查看帮助
uv --help

# 检查 Python 版本管理
uv python list

3.3 环境配置

配置文件位置

全局配置: ~/.config/uv/uv.toml (Linux/Mac) 或 %APPDATA%\uv\uv.toml (Windows)
项目配置: pyproject.toml 中的 [tool.uv] 部分

示例配置

toml

# ~/.config/uv/uv.toml (全局配置)
[tool.uv]
# 默认 Python 版本
python = "3.11"

# 镜像源配置（国内用户推荐）
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

# 缓存目录
cache-dir = "~/.cache/uv"

# 虚拟环境目录
venv-dir = ".venv"

4. 基础使用教程

4.1 项目初始化

创建新项目

bash

# 创建新的 Python 项目
uv init my-project
cd my-project

# 查看生成的文件结构
ls -la
# .
# ├── .python-version    # Python 版本文件
# ├── pyproject.toml     # 项目配置文件
# ├── README.md          # 项目说明
# └── src/
#     └── my_project/
#         └── __init__.py

在现有项目中初始化

bash

# 在现有项目目录中
cd existing-project

# 初始化 uv 项目（不创建额外文件）
uv init --no-readme --no-pin-python

# 这会生成 pyproject.toml 文件

4.2 Python 版本管理

bash

# 查看可用的 Python 版本
uv python list

# 安装特定 Python 版本
uv python install 3.11.0
uv python install 3.12.0

# 为项目设置 Python 版本
uv python pin 3.11.0

# 查看当前项目使用的 Python 版本
uv python show

4.3 虚拟环境管理

bash

# 创建虚拟环境（自动检测 Python 版本）
uv venv

# 创建指定 Python 版本的虚拟环境
uv venv --python 3.11

# 创建虚拟环境到指定目录
uv venv .venv

# 激活虚拟环境（可选，uv run 会自动使用）
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate

# 查看虚拟环境信息
uv venv --show-path

4.4 依赖管理

添加依赖

bash

# 添加运行时依赖
uv add fastapi
uv add "fastapi>=0.100.0"
uv add fastapi uvicorn pydantic

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

# 添加可选依赖组
uv add --optional-group test pytest pytest-asyncio
uv add --optional-group lint black isort

安装依赖

bash

# 安装所有依赖（类似 npm install）
uv sync

# 只安装运行时依赖（不安装开发依赖）
uv sync --no-dev

# 安装特定的可选依赖组
uv sync --extra test

移除依赖

bash

# 移除依赖
uv remove fastapi

# 移除开发依赖
uv remove --dev pytest

更新依赖

bash

# 更新所有依赖到最新版本
uv lock --upgrade

# 更新特定依赖
uv lock --upgrade-package fastapi

# 查看过时的依赖
uv tree --outdated

4.5 运行命令

bash

# 在虚拟环境中运行 Python 脚本
uv run python app.py
uv run python -m app.main

# 运行 Python 模块
uv run uvicorn app.main:app --reload

# 运行测试
uv run pytest
uv run python -m pytest

# 运行格式化工具
uv run black .
uv run isort .

# 临时安装并运行工具（类似 npx）
uv run --with requests python -c "import requests; print(requests.get('https://httpbin.org/json').json())"

4.6 常用命令速查

命令	功能	前端类比
`uv init`	初始化项目	`npm init`
`uv add package`	添加依赖	`npm install package`
`uv remove package`	移除依赖	`npm uninstall package`
`uv sync`	安装所有依赖	`npm install`
`uv run command`	运行命令	`npm run command`
`uv lock`	更新锁文件	`npm update`
`uv tree`	查看依赖树	`npm list`

5. 实际项目迁移指南

5.1 从 requirements.txt 迁移

步骤 1：备份现有配置

bash

# 备份现有文件
cp requirements.txt requirements.txt.backup
cp .python-version .python-version.backup 2>/dev/null || true

步骤 2：初始化 uv 项目

bash

# 在项目根目录初始化
uv init --no-readme --no-pin-python

# 设置 Python 版本（如果有 .python-version 文件）
uv python pin $(cat .python-version)

步骤 3：导入依赖

bash

# 方法1：逐个添加依赖（推荐，可以区分开发依赖）
uv add fastapi==0.104.1
uv add uvicorn[standard]==0.24.0
uv add --dev pytest black

# 方法2：批量导入（快速但不区分依赖类型）
cat requirements.txt | grep -v "^#" | xargs uv add

步骤 4：验证迁移

bash

# 同步依赖
uv sync

# 测试应用启动
uv run python -m app.main

# 运行测试（如果有）
uv run pytest

步骤 5：更新 Docker 配置

dockerfile

# 更新 Dockerfile
FROM python:3.11-slim

# 安装 uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

WORKDIR /app

# 复制项目文件
COPY pyproject.toml uv.lock ./

# 安装依赖
RUN uv sync --frozen --no-dev

# 复制应用代码
COPY . .

# 使用 uv 运行应用
CMD ["uv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

5.2 从 Poetry 迁移

bash

# 1. 备份 poetry 配置
cp pyproject.toml pyproject.toml.backup
cp poetry.lock poetry.lock.backup 2>/dev/null || true

# 2. 转换 poetry 配置到 uv 格式
# 手动编辑 pyproject.toml，将 [tool.poetry] 部分转换为 [project]
# 或者重新初始化
uv init --no-readme --no-pin-python

# 3. 从 poetry 依赖列表添加到 uv
# 查看 poetry 依赖
poetry show

# 逐个添加到 uv
uv add $(poetry show --only=main --no-dev | awk '{print $1}')
uv add --dev $(poetry show --only=dev | awk '{print $1}')

# 4. 移除 poetry 文件（可选）
rm poetry.lock

5.3 团队协作迁移策略

渐进式迁移计划

阶段 1：个人开发环境

bash

# 开发者个人先尝试 uv
uv init --no-readme --no-pin-python
uv add $(cat requirements.txt | grep -v "^#" | tr '\n' ' ')
uv sync
uv run python -m app.main

阶段 2：CI/CD 环境

yaml

# GitHub Actions 示例
name: Test with uv
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install uv
        uses: astral-sh/setup-uv@v1
      - name: Set up Python
        run: uv python install 3.11
      - name: Install dependencies
        run: uv sync
      - name: Run tests
        run: uv run pytest

阶段 3：生产环境

bash

# 更新部署脚本
# 替换 pip install -r requirements.txt
# 为 uv sync --frozen --no-dev

6. 最佳实践

6.1 项目结构建议

my-project/
├── .python-version      # Python 版本锁定
├── pyproject.toml       # 项目配置和依赖
├── uv.lock             # 依赖锁文件（提交到 git）
├── .venv/              # 虚拟环境（不提交到 git）
├── src/
│   └── my_project/
│       ├── __init__.py
│       └── main.py
├── tests/
│   └── test_main.py
├── docs/
└── README.md

6.2 pyproject.toml 配置示例

toml

[project]
name = "my-project"
version = "0.1.0"
description = "My awesome Python project"
readme = "README.md"
requires-python = ">=3.11"
authors = [
    {name = "Your Name", email = "your.email@example.com"}
]
classifiers = [
    "Development Status :: 4 - Beta",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.11",
]

# 运行时依赖
dependencies = [
    "fastapi>=0.100.0",
    "uvicorn[standard]>=0.24.0",
    "pydantic>=2.0.0",
    "httpx>=0.25.0",
]

# 可选依赖组
[project.optional-dependencies]
test = [
    "pytest>=7.0.0",
    "pytest-asyncio>=0.21.0",
    "httpx>=0.25.0",
]
lint = [
    "black>=23.0.0",
    "isort>=5.12.0",
    "flake8>=6.0.0",
]
dev = [
    "my-project[test,lint]",
    "pre-commit>=3.0.0",
]

# 项目脚本
[project.scripts]
my-app = "my_project.main:main"

# uv 特定配置
[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
    "black>=23.0.0",
    "isort>=5.12.0",
]

# 其他工具配置
[tool.black]
line-length = 88
target-version = ['py311']

[tool.isort]
profile = "black"
line_length = 88

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

6.3 团队协作规范

Git 配置

bash

# .gitignore 添加
.venv/
__pycache__/
*.pyc
.pytest_cache/

# 提交 uv.lock 文件
git add uv.lock
git commit -m "Add uv.lock for dependency locking"

开发环境设置脚本

bash

#!/bin/bash
# setup-dev.sh

echo "Setting up development environment..."

# 检查 uv 是否安装
if ! command -v uv &> /dev/null; then
    echo "Installing uv..."
    curl -LsSf https://astral.sh/uv/install.sh | sh
fi

# 设置 Python 版本
uv python install 3.11.0
uv python pin 3.11.0

# 创建虚拟环境并安装依赖
uv venv
uv sync --extra dev

# 安装 pre-commit hooks
uv run pre-commit install

echo "Development environment setup complete!"
echo "Run 'uv run python -m app.main' to start the application"

6.4 性能优化技巧

加速依赖安装

bash

# 使用国内镜像源
uv add --index-url https://pypi.tuna.tsinghua.edu.cn/simple fastapi

# 或在配置文件中设置
# ~/.config/uv/uv.toml
[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

缓存优化

bash

# 查看缓存使用情况
uv cache info

# 清理缓存
uv cache clean

# 预热缓存（在 CI 中有用）
uv cache prune --ci

7. 常见问题与解决方案

7.1 安装问题

问题：Windows 上安装失败

powershell

# 解决方案1：使用管理员权限
# 以管理员身份运行 PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 解决方案2：手动下载安装
# 从 GitHub releases 下载对应版本
# https://github.com/astral-sh/uv/releases

问题：权限错误

bash

# Linux/Mac 权限问题
sudo chown -R $USER ~/.local/bin/uv
chmod +x ~/.local/bin/uv

# 添加到 PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

7.2 依赖管理问题

问题：依赖冲突

bash

# 查看依赖冲突详情
uv tree --show-duplicates

# 解决方案：更新锁文件
uv lock --upgrade

# 强制重新解析依赖
uv sync --refresh

问题：包找不到

bash

# 检查索引源
uv index list

# 添加额外的索引源
uv add --index-url https://pypi.org/simple package-name

# 使用本地包
uv add ./local-package
uv add git+https://github.com/user/repo.git

问题：虚拟环境问题

bash

# 删除并重新创建虚拟环境
rm -rf .venv
uv venv
uv sync

# 查看虚拟环境状态
uv venv --show-path
uv python show

7.3 性能问题

问题：安装速度慢

bash

# 使用国内镜像源
export UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"

# 或在配置文件中永久设置
mkdir -p ~/.config/uv
cat > ~/.config/uv/uv.toml << EOF
[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
EOF

问题：磁盘空间不足

bash

# 清理缓存
uv cache clean

# 查看缓存大小
uv cache info

# 设置缓存大小限制
uv cache clean --size 1GB

8. 高级功能

8.1 工作空间管理

多包项目结构

workspace/
├── pyproject.toml          # 工作空间配置
├── packages/
│   ├── package-a/
│   │   ├── pyproject.toml
│   │   └── src/
│   └── package-b/
│       ├── pyproject.toml
│       └── src/
└── apps/
    └── web-app/
        ├── pyproject.toml
        └── src/

工作空间配置

toml

# 根目录 pyproject.toml
[tool.uv.workspace]
members = [
    "packages/*",
    "apps/*"
]

# 共享依赖
[tool.uv.workspace.dependencies]
pytest = ">=7.0.0"
black = ">=23.0.0"

8.2 脚本管理

定义项目脚本

toml

# pyproject.toml
[project.scripts]
start = "my_project.main:main"
dev = "my_project.dev:run_dev_server"
test = "pytest"
lint = "black ."

运行脚本

bash

# 运行定义的脚本
uv run start
uv run dev
uv run test
uv run lint

# 等同于
uv run python -m my_project.main
uv run python -m my_project.dev
uv run pytest
uv run black .

8.3 环境变量管理

.env 文件支持

bash

# .env 文件
DATABASE_URL=postgresql://localhost/mydb
DEBUG=true
SECRET_KEY=your-secret-key

在脚本中使用

python

# main.py
import os
from dotenv import load_dotenv

load_dotenv()

DATABASE_URL = os.getenv('DATABASE_URL')
DEBUG = os.getenv('DEBUG', 'false').lower() == 'true'

8.4 自定义索引和源

配置多个索引源

toml

# pyproject.toml
[tool.uv.sources]
# 私有包索引
my-private-package = { index = "https://private.pypi.example.com/simple" }

# Git 仓库
my-git-package = { git = "https://github.com/user/repo.git", tag = "v1.0.0" }

# 本地路径
my-local-package = { path = "../local-package" }

9. 实战案例

9.1 基于 model-gateway 项目的完整迁移

当前项目分析

bash

# 查看当前项目结构
tree -I '__pycache__|*.pyc|.git'
# model-gateway/
# ├── .env
# ├── .python-version      # Python 3.11.0
# ├── requirements.txt     # 14个依赖包
# ├── Dockerfile
# ├── docker-compose.yml
# ├── app/
# │   ├── main.py
# │   ├── config.py
# │   └── ...
# └── docs/

步骤 1：准备迁移

bash

# 1. 备份现有配置
cp requirements.txt requirements.txt.backup
cp .python-version .python-version.backup

# 2. 安装 uv（如果还没安装）
pip install uv

# 3. 验证当前环境
python --version  # Python 3.11.0
pip list > current_packages.txt

步骤 2：初始化 uv 项目

bash

# 初始化 uv 项目
uv init --no-readme --no-pin-python

# 设置 Python 版本
uv python pin 3.11.0

# 查看生成的 pyproject.toml
cat pyproject.toml

步骤 3：迁移依赖

bash

# 逐个添加运行时依赖
uv add fastapi==0.104.1
uv add uvicorn[standard]==0.24.0
uv add pydantic==2.5.0
uv add pydantic-settings==2.1.0
uv add python-multipart==0.0.6
uv add httpx==0.25.2
uv add redis==5.0.1
uv add sqlalchemy==2.0.23
uv add alembic==1.12.1
uv add psycopg2-binary==2.9.9
uv add python-jose[cryptography]==3.3.0
uv add passlib[bcrypt]==1.7.4
uv add structlog==23.2.0
uv add prometheus-client==0.19.0

# 添加开发依赖
uv add --dev pytest pytest-asyncio
uv add --dev black isort flake8
uv add --dev pre-commit

步骤 4：更新项目配置

toml

# pyproject.toml 最终配置
[project]
name = "model-gateway"
version = "1.0.0"
description = "AI Model Gateway Service"
readme = "README.md"
requires-python = ">=3.11"
authors = [
    {name = "Your Team", email = "team@example.com"}
]

dependencies = [
    "fastapi==0.104.1",
    "uvicorn[standard]==0.24.0",
    "pydantic==2.5.0",
    "pydantic-settings==2.1.0",
    "python-multipart==0.0.6",
    "httpx==0.25.2",
    "redis==5.0.1",
    "sqlalchemy==2.0.23",
    "alembic==1.12.1",
    "psycopg2-binary==2.9.9",
    "python-jose[cryptography]==3.3.0",
    "passlib[bcrypt]==1.7.4",
    "structlog==23.2.0",
    "prometheus-client==0.19.0",
]

# 开发依赖
[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
    "pytest-asyncio>=0.21.0",
    "black>=23.0.0",
    "isort>=5.12.0",
    "flake8>=6.0.0",
    "pre-commit>=3.0.0",
]

# 项目脚本
[project.scripts]
start = "app.main:main"
dev = "uvicorn app.main:app --reload --host 0.0.0.0 --port 8000"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

步骤 5：验证迁移

bash

# 同步依赖
uv sync

# 测试应用启动
uv run python -m app.main

# 或使用定义的脚本
uv run dev

# 运行测试
uv run pytest

# 代码格式化
uv run black .
uv run isort .

步骤 6：更新 Docker 配置

dockerfile

# 更新后的 Dockerfile
FROM python:3.11-slim

# 安装 uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

# 设置工作目录
WORKDIR /app

# 设置环境变量
ENV PYTHONPATH=/app
ENV PYTHONUNBUFFERED=1

# 复制项目配置文件
COPY pyproject.toml uv.lock ./

# 安装依赖（生产环境不安装开发依赖）
RUN uv sync --frozen --no-dev

# 复制应用代码
COPY . .

# 创建非root用户
RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
USER appuser

# 健康检查
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/api/v1/health || exit 1

# 暴露端口
EXPOSE 8000

# 使用 uv 运行应用
CMD ["uv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

步骤 7：更新 CI/CD 配置

yaml

# .github/workflows/test.yml
name: Test Model Gateway
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: password
          POSTGRES_DB: testdb
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

      redis:
        image: redis:7
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v1

      - name: Set up Python
        run: uv python install 3.11

      - name: Install dependencies
        run: uv sync

      - name: Run linting
        run: |
          uv run black --check .
          uv run isort --check-only .
          uv run flake8 .

      - name: Run tests
        run: uv run pytest
        env:
          DATABASE_URL: postgresql://postgres:password@localhost/testdb
          REDIS_URL: redis://localhost:6379

9.2 性能对比测试

安装速度对比

bash

# 传统方式
time pip install -r requirements.txt
# 结果：约 45 秒

# uv 方式
time uv sync
# 结果：约 3 秒

# 性能提升：15x 更快！

依赖解析对比

bash

# 传统方式（可能出现冲突）
pip install fastapi==0.104.1 pydantic==1.10.0
# 可能出现兼容性问题

# uv 方式（智能解析）
uv add fastapi==0.104.1 pydantic==1.10.0
# 自动检测并解决版本冲突

9.3 团队协作效果

开发环境一致性

bash

# 团队成员 A
uv sync
# 安装完全相同的依赖版本

# 团队成员 B
uv sync
# 安装完全相同的依赖版本

# 确保所有人使用相同的依赖版本

新人入职体验

bash

# 传统方式
git clone project
cd project
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python app.py

# uv 方式
git clone project
cd project
uv sync
uv run python -m app.main

📝 总结

✅ uv 的优势总结

🚀 极致性能 - 比 pip 快 10-100 倍
🔧 统一工具链 - 一个工具解决所有问题
🎯 现代化设计 - 符合现代 Python 开发标准
💡 前端友好 - 与 npm/yarn 工作流程相似
🔒 依赖锁定 - 确保团队环境一致性
⚡ 智能解析 - 自动解决依赖冲突

🎯 适用场景

✅ 新项目 - 直接使用 uv 开始
✅ 现有项目迁移 - 渐进式迁移策略
✅ 团队协作 - 统一开发环境
✅ CI/CD - 加速构建流程
✅ 前端开发者 - 降低 Python 学习成本

🚀 下一步行动

立即尝试 - 在个人项目中安装和使用 uv
团队推广 - 分享本文档给团队成员
渐进迁移 - 按照文档中的迁移策略逐步替换现有项目
持续学习 - 关注 uv 的最新功能和最佳实践

📚 参考资源

官方文档: https://docs.astral.sh/uv/
GitHub 仓库: https://github.com/astral-sh/uv
发布说明: https://github.com/astral-sh/uv/releases
社区讨论: https://github.com/astral-sh/uv/discussions

💬 反馈与支持

如果你在使用 uv 过程中遇到问题，或者对本文档有任何建议，欢迎：

在团队内部分享使用经验
提交 issue 到 uv 官方仓库
参与社区讨论和贡献

最后更新: 2025 年 1 月 27 日
文档版本: v1.0
适用 uv 版本: 0.1.0+

🎉 恭喜！ 你已经掌握了 uv 的完整使用方法。现在就开始在你的项目中使用 uv，体验现代化 Python 开发的便利吧！

Python uv 完整使用指南 ​

📖 目录 ​

1. uv 简介与背景 ​

1.1 什么是 uv？ ​

1.2 为什么选择 uv？ ​

🚀 极致性能 ​

🔧 统一工具链 ​

🎯 现代化设计 ​

1.3 uv vs 传统工具对比 ​

2. 前端开发者友好的类比 ​

2.1 概念映射表 ​

2.2 工作流对比 ​

前端项目工作流 ​

Python 项目工作流（uv 方式） ​

Python 项目工作流（传统方式） ​

3. 安装与环境配置 ​

3.1 安装 uv ​

Windows 安装 ​

macOS 安装 ​

Linux 安装 ​

3.2 验证安装 ​

3.3 环境配置 ​

配置文件位置 ​

示例配置 ​

4. 基础使用教程 ​

4.1 项目初始化 ​

创建新项目 ​

在现有项目中初始化 ​

4.2 Python 版本管理 ​

4.3 虚拟环境管理 ​

4.4 依赖管理 ​

添加依赖 ​

安装依赖 ​

移除依赖 ​

更新依赖 ​

4.5 运行命令 ​

4.6 常用命令速查 ​

5. 实际项目迁移指南 ​

5.1 从 requirements.txt 迁移 ​

步骤 1：备份现有配置 ​

步骤 2：初始化 uv 项目 ​

步骤 3：导入依赖 ​

步骤 4：验证迁移 ​

步骤 5：更新 Docker 配置 ​

5.2 从 Poetry 迁移 ​

5.3 团队协作迁移策略 ​

渐进式迁移计划 ​

6. 最佳实践 ​

6.1 项目结构建议 ​

6.2 pyproject.toml 配置示例 ​

6.3 团队协作规范 ​

Git 配置 ​

开发环境设置脚本 ​

6.4 性能优化技巧 ​

加速依赖安装 ​

缓存优化 ​

7. 常见问题与解决方案 ​

7.1 安装问题 ​

问题：Windows 上安装失败 ​

问题：权限错误 ​

7.2 依赖管理问题 ​

问题：依赖冲突 ​

问题：包找不到 ​

问题：虚拟环境问题 ​

7.3 性能问题 ​

问题：安装速度慢 ​

问题：磁盘空间不足 ​

8. 高级功能 ​

8.1 工作空间管理 ​

多包项目结构 ​

工作空间配置 ​

8.2 脚本管理 ​

定义项目脚本 ​

运行脚本 ​

8.3 环境变量管理 ​

.env 文件支持 ​

在脚本中使用 ​

8.4 自定义索引和源 ​

配置多个索引源 ​

9. 实战案例 ​

Python uv 完整使用指南

📖 目录

1. uv 简介与背景

1.1 什么是 uv？

1.2 为什么选择 uv？

🚀 极致性能

🔧 统一工具链

🎯 现代化设计

1.3 uv vs 传统工具对比

2. 前端开发者友好的类比

2.1 概念映射表

2.2 工作流对比

前端项目工作流

Python 项目工作流（uv 方式）

Python 项目工作流（传统方式）

3. 安装与环境配置

3.1 安装 uv

Windows 安装

macOS 安装

Linux 安装

3.2 验证安装

3.3 环境配置

配置文件位置

示例配置

4. 基础使用教程

4.1 项目初始化

创建新项目

在现有项目中初始化

4.2 Python 版本管理

4.3 虚拟环境管理

4.4 依赖管理

添加依赖

安装依赖

移除依赖

更新依赖

4.5 运行命令

4.6 常用命令速查

5. 实际项目迁移指南

5.1 从 requirements.txt 迁移

步骤 1：备份现有配置

步骤 2：初始化 uv 项目

步骤 3：导入依赖

步骤 4：验证迁移

步骤 5：更新 Docker 配置

5.2 从 Poetry 迁移

5.3 团队协作迁移策略

渐进式迁移计划

6. 最佳实践

6.1 项目结构建议

6.2 pyproject.toml 配置示例

6.3 团队协作规范

Git 配置

开发环境设置脚本

6.4 性能优化技巧

加速依赖安装

缓存优化

7. 常见问题与解决方案

7.1 安装问题

问题：Windows 上安装失败

问题：权限错误

7.2 依赖管理问题

问题：依赖冲突

问题：包找不到

问题：虚拟环境问题

7.3 性能问题

问题：安装速度慢

问题：磁盘空间不足

8. 高级功能

8.1 工作空间管理

多包项目结构

工作空间配置

8.2 脚本管理

定义项目脚本

运行脚本

8.3 环境变量管理

.env 文件支持

在脚本中使用

8.4 自定义索引和源

配置多个索引源

9. 实战案例