uv 是 Astral（Ruff 团队）的 Python 项目管理器，Rust 写的，
比 pip + venv + pip-tools 快 10-100 倍。2024 之后基本是新项目的默认。
下面 5 分钟起一个 Django 5 项目。
1. 装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或 macOS: brew install uv
# 或 Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
uv --version
2. 起项目
uv init myapp --python 3.12
cd myapp
uv init 生成 pyproject.toml + .python-version + hello.py，
不创建 venv 直到需要。
3. 加依赖
uv add django gunicorn psycopg[binary] python-dotenv
uv add --dev ruff pytest pytest-django
uv add 会：
- 解析依赖（极快）
- 写入
pyproject.toml - 锁定到
uv.lock - 装到
.venv/（自动创建）
psycopg[binary] 是 psycopg3 的预编译版（生产建议 psycopg[c] 自己编）。
4. Django 项目结构
uv run django-admin startproject myapp .
uv run python manage.py startapp blog
uv run 等价于"在项目 venv 里跑"。比 source .venv/bin/activate && python ...
直接，跨 shell / CI 都一样。
5. 跑
uv run python manage.py migrate
uv run python manage.py createsuperuser
uv run python manage.py runserver
6. CI / Docker 中使用
Dockerfile：
FROM python:3.12-slim
# 装 uv 二进制
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock ./
# --frozen 严格按 lock 安装，不解析
RUN uv sync --frozen --no-install-project
COPY . .
RUN uv sync --frozen
EXPOSE 8000
CMD ["uv", "run", "gunicorn", "myapp.wsgi:application", "-b", "0.0.0.0:8000"]
GitHub Actions：
- uses: astral-sh/setup-uv@v3
with:
enable-cache: true
- run: uv sync --frozen
- run: uv run pytest
enable-cache: true 跨 job 缓存 wheel，CI 飞快。
7. 升级 / 锁定
uv lock --upgrade-package django # 只升 django
uv lock --upgrade # 全部升到最新允许的范围
uv add 'django>=5.1,<6' # 改约束
uv pip compile pyproject.toml > requirements.txt # 兼容 pip 导出
8. 与 pip / poetry 对比
| 操作 | pip / pip-tools | uv |
|---|---|---|
| 装 100 个依赖 | 30-60s | 1-3s |
| 解析 lock | 几秒到几十秒 | < 1s |
| 创建 venv | python -m venv .venv (慢) |
自动且快 |
| 跨平台 lock | 麻烦 | 内置 |
| Python 多版本 | pyenv 配合 | uv python install 3.12 内置 |
踩过的坑
uv.lock必须进 git。它包含跨平台依赖锁，删了会让uv sync --frozen失败。uv add默认只在主 group；要 dev 依赖加--dev；要 optional group
加--optional groupname。psycopg[binary]在 musl-libc（Alpine）镜像上没预编译 wheel，会回退到
源码编译——慢。改用python:3.12-slim（glibc）镜像。- VSCode 自动识别
.venv/—— 但要把 Python 解释器手动选为.venv/bin/python，
否则 import 检查走系统 Python。
登录后参与评论。