Both Dockerfile examples should probably include UV_SYSTEM_PYTHON=true

[joejoinerr]

I got caught out using these examples, since both the standard and multistage built fine. However, the multistage image wouldn't run, instead exiting with a ModuleNotFoundError.

It took a while to figure out, but I found that because my .python-version file, which contained a different version to that specified on the container image, had been copied during the build, uv was using that to install and run, which later broke the app.

This can be overcome by specifiying UV_SYSTEM_PYTHON=true as an env to make sure that the container-specified Python version is used.

The docs also specify it for this purpose:

UV_SYSTEM_PYTHON=true is intended for use in continuous integration (CI) or containerized environments

https://docs.astral.sh/uv/configuration/environment/#UV_SYSTEM_PYTHON

[zanieb]

Mmm interesting. Maybe we should add the .python-version file to the .dockerignore?

[joejoinerr]

Yeah that also works. I have both in my project now, but I like the environment variable since it sits alongside the other build-specific settings. e.g.

ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy UV_SYSTEM_PYTHON=true

[zanieb]

I worry that UV_SYSTEM_PYTHON will imply to people that we'll install into the system Python environment — which we do not.

[joejoinerr]

Ah, makes sense. Well from my brief tests, both solutions seem to have the same effect. So it's up to you :)