为何Docker环境中使用uv run运行Python应用会触发构建，本地环境却无此现象？

这问题我之前折腾uv + Docker时也碰到过类似的，咱们一步步拆解背后的原因：

核心差异：本地和Docker里项目包的安装状态不一样 #

你本地执行uv sync后，输出里明确显示+ project-name==0.1.0 (from file:///home/fmppo/projects/so-question)——这说明uv已经把你的项目本身当成一个包，安装到本地的.venv虚拟环境里了。之后你跑uv run src/hello_world.py时，uv直接调用虚拟环境里已经装好的src包，自然不需要再构建一次。

但在Docker容器里，情况就不一样了，虽然你也跑了uv sync，但大概率是以下两种情况导致项目包没被正确识别：

• 虚拟环境没被uv run用上
  本地的uv默认会创建.venv，而且uv run会自动加载这个虚拟环境里的内容。但Docker镜像里的uv，可能因为默认配置（比如环境变量、运行用户是root）的问题，uv sync虽然创建了虚拟环境，但uv run却没用到它，直接用了系统Python环境——而系统Python里根本没装你的项目包。
  当uv发现你脚本里导入了src.utils但系统环境里找不到这个包时，就会自动触发项目的构建和临时安装，也就是你看到的Built project-name @ file:///app、卸载再安装包的那串日志。

• uv版本或默认行为有差异
  你本地的uv版本和Docker镜像（ghcr.io/astral-sh/uv:python3.12-bookworm-slim）里的uv版本可能不一样，旧版本的uv sync可能不会自动把当前目录的根项目（对应pyproject.toml的项目）安装到环境里，只会同步你那空的依赖列表，导致环境里完全没项目包。

给你几个解决的小方案 #

针对这个问题，你可以试试下面这几种办法：

方案1：强制uv run用虚拟环境

修改Dockerfile的ENTRYPOINT，明确指定使用uv sync创建的.venv：

ENTRYPOINT [ "uv", "run", "--venv", ".venv", "src/hello_world.py" ]

或者在uv sync之前加环境变量，让uv默认就用虚拟环境：

ENV UV_VENV_DIR="/app/.venv"
ENV UV_VENV_PROMPT="project-name"

RUN uv sync
ENTRYPOINT [ "uv", "run", "src/hello_world.py" ]

方案2：手动先把项目装到环境里

在Dockerfile里uv sync之后，加一步手动安装项目的命令，确保包被装进去：

RUN uv sync
RUN uv pip install .
ENTRYPOINT [ "uv", "run", "src/hello_world.py" ]

方案3：用模块方式运行脚本

别直接跑src/hello_world.py，改用模块方式启动，uv会优先用已安装的包模块，不会触发自动构建：

ENTRYPOINT [ "uv", "run", "-m", "src.hello_world" ]

随便选一种改完，再构建镜像运行，应该就不会再看到那串构建日志了~

备注：内容来源于stack exchange，提问作者Frederico Portela