From 35e2f67b5e4529050e615f6e812d0d727afc20d3 Mon Sep 17 00:00:00 2001
From: samypr100 <3933065+samypr100@users.noreply.github.com>
Date: Sat, 21 Jun 2025 15:42:28 -0400
Subject: [PATCH] feat(docker): set default `UV_TOOL_BIN_DIR` on docker images
 (#13391)

Closes #13057

Sets `UV_TOOL_BIN_DIR` to `/usr/local/bin` for all derived images to
allow `uv tool install` to work out of the box.

Note, when the default image user is overwritten (e.g. `USER <UID>`) by
a less privileged one, an alternative writable location would now need
to be set by downstream consumers to prevent issues, hence I'm labeling
this as a breaking change for 0.8.x release.

Relates to https://github.com/astral-sh/uv-docker-example/pull/55

Each image was tested to work with uv tool with `UV_TOOL_BIN_DIR` set to
`/usr/local/bin` with the default root user and alternative non-root
users to confirm breaking nature of the change.
---
 .github/workflows/build-docker.yml | 1 +
 docs/guides/integration/docker.md  | 3 +++
 2 files changed, 4 insertions(+)

diff --git a/.github/workflows/build-docker.yml b/.github/workflows/build-docker.yml
index 843ee8dfb..3c080b63f 100644
--- a/.github/workflows/build-docker.yml
+++ b/.github/workflows/build-docker.yml
@@ -225,6 +225,7 @@ jobs:
           cat <<EOF > Dockerfile
           FROM ${BASE_IMAGE}
           COPY --from=${{ env.UV_GHCR_IMAGE }}:latest /uv /uvx /usr/local/bin/
+          ENV UV_TOOL_BIN_DIR="/usr/local/bin"
           ENTRYPOINT []
           CMD ["/usr/local/bin/uv"]
           EOF
diff --git a/docs/guides/integration/docker.md b/docs/guides/integration/docker.md
index 2ea14c9b0..a75228723 100644
--- a/docs/guides/integration/docker.md
+++ b/docs/guides/integration/docker.md
@@ -77,6 +77,9 @@ As with the distroless image, each derived image is published with uv version ta
 `ghcr.io/astral-sh/uv:{major}.{minor}.{patch}-{base}` and
 `ghcr.io/astral-sh/uv:{major}.{minor}-{base}`, e.g., `ghcr.io/astral-sh/uv:0.7.22-alpine`.
 
+In addition, starting with `0.8` each derived image also sets `UV_TOOL_BIN_DIR` to `/usr/local/bin`
+to allow `uv tool install` to work as expected with the default user.
+
 For more details, see the [GitHub Container](https://github.com/astral-sh/uv/pkgs/container/uv)
 page.