docker容器中uv的使用

TL;DR

本文记录uv在docker容器中使用注意点,

uv简介

uv是用rust编写的一个python包管理器，特点是速度快，且功能强大，目标是替代pip,不仅能管理python项目的依赖，还能很容易的切换python版本(venv的方式). 更详细的介绍可以参考笔者的另一篇博客 uv: 一个统一的Python包管理工具.

uv管理项目依赖

用uv管理项目的依赖大致遵循以下的过程

step 1

初始化项目

uv init

uv会创建pyproject.toml来记录工程的版本信息，依赖包等.

step 2

创建venv，可以指定python版本，即使本地没有这个指定的python版本，uv也可以自动下载,这个就比poetry更好用了

uv venv --python 3.12

安装后激活环境

Windows

.\venv\Scripts\activate.ps1

Linux/Mac

.venv/bin/activate

step 3

安装依赖项,和pip 用法类似

uv add numpy

甚至还可以让uv运行pip安装

uv pip install numpy

注意，uv add是会把依赖包写入到pyproject.toml中的，但是uv pip install不会.

如果要使用镜像加速安装，和pip用法是一样的，例如

uv add numpy -i https://mirrors.aliyun.com/pypi/simple

依赖包恢复

uv会创建uv.lock来锁定依赖信息，确保在恢复的时候保持一致. 运行如下命令即可.

uv sync

在Docker容器中使用uv

我们用一个fastapi的web项目来作为例子,基础镜像是 python:3.12-alpine.

在docker容器中使用uv，首先可以用pip安装

FROM python:3.12-alpine

RUN pip install --no-cache-dir uv

然后copy 项目依赖信息，安装依赖

COPY pyproject.toml .
RUN uv sync

这样做是利用docker的cache机制，代码变更频率比依赖的变更频率高，在恢复依赖包之后再复制代码，可以有效加速image的build.

重点在下面:
实测发现，安装uv后直接uv sync,的确会成功的安装依赖，但是，安装的并非在base image的python目录下, uv自动创建了一个venv. 所以如果安装依赖后如果直接运行

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

此时会报找不到uvicorn，因为uv创建的venv不在系统的PATH中. 解决办法很简单，把这个目录加入到PATH

ENV PATH="/app/.venv/bin:$PATH"

这样就能运行了.

最终的Dockerfile大致如下，仅供参考

FROM python:3.12-alpine
WORKDIR /app
COPY pyproject.toml .
RUN pip install --no-cache-dir uv && \
    uv sync
ENV PATH="/app/.venv/bin:$PATH"
COPY . .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]