python项目及包管理uv

Posted on Views:

uv 是 Astral 推出的 Python包管理与项目管理工具，目标是替代：

  • pip
  • virtualenv
  • pip-tools
  • poetry
  • pyenv（部分能力）

核心特点：

  • Rust 编写，速度极快
  • 原生虚拟环境管理
  • 锁文件管理
  • 兼容 pyproject.toml
  • 支持 workspace
  • 支持 Python 安装管理

uv 官方文档

1.安装 uv

1.1 Linux / macOS

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

验证：

1
uv --version

1.2 Homebrew

1
brew install uv

1.3 Windows

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

2.创建 Python 项目

2.1 最基础创建

1
uv init myapp

目录：

1
2
3
4
5
myapp/
├── .python-version
├── README.md
├── main.py
├── pyproject.toml

进入项目：

1
cd myapp

运行：

1
uv run main.py

2.2 创建包项目（推荐）

创建可发布 package：

1
uv init --package mylib

结构：

1
2
3
4
5
6
mylib/
├── pyproject.toml
├── README.md
├── src/
│   └── mylib/
│       └── __init__.py

这是现代 Python 推荐结构。

3.创建虚拟环境

3.1 自动创建

执行：

1
uv sync

会自动：

  • 创建 .venv
  • 安装依赖
  • 生成锁文件

目录：

1
2
.venv/
uv.lock

3.2 指定 Python 版本

1
uv venv --python 3.12

或者：

1
2
uv python install 3.12
uv venv --python 3.12

4.安装依赖

4.1 安装运行依赖

1
uv add requests

自动更新：

  • pyproject.toml
  • uv.lock

4.2 开发依赖

1
uv add --dev pytest black ruff

4.3 指定版本

1
uv add "fastapi>=0.115"

5.运行项目

5.1 运行 Python

1
uv run python app.py

5.2 运行模块

1
uv run -m myapp

5.3 运行工具

1
2
uv run pytest
uv run ruff check .

无需手动 activate venv。

6.pyproject.toml 示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
[project]
name = "myapp"
version = "0.1.0"
description = "example"
readme = "README.md"
requires-python = ">=3.11"

dependencies = [
    "fastapi",
    "uvicorn",
]

[dependency-groups]
dev = [
    "pytest",
    "ruff",
]
# 定义默认包索引
[[tool.uv.index]]
url="https://pypi.tuna.tsinghua.edu.cn/simple"
default=true

7.常用命令速查

功能 命令
初始化项目 uv init
初始化 package uv init --package
创建 venv uv venv
安装依赖 uv add
删除依赖 uv remove
安装全部依赖 uv sync
更新锁文件 uv lock
运行程序 uv run
安装 Python uv python install

8.推荐工作流（SRE/DevOps 场景）

8.1 创建服务

1
2
uv init --package ai-service
cd ai-service

8.2 安装依赖

1
2
uv add fastapi uvicorn pydantic
uv add --dev pytest ruff mypy

8.3 启动

1
uv run uvicorn ai_service.main:app --reload

8.4 Docker 集成

1
2
3
4
5
6
7
8
9
10
11
FROM python:3.12-slim

COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app

COPY . .

RUN uv sync --frozen

CMD ["uv", "run", "python", "main.py"]

9.uv 工作流架构

flowchart TD

A[uv init] --> B[pyproject.toml]

B --> C[uv add]
C --> D[uv.lock]

D --> E[uv sync]

E --> F[.venv]

F --> G[uv run]