Skip to content

Add uv tool dir to PATH in uv docker images#18080

Closed
konstin wants to merge 1 commit intomainfrom
konsti/docker-tool-path
Closed

Add uv tool dir to PATH in uv docker images#18080
konstin wants to merge 1 commit intomainfrom
konsti/docker-tool-path

Conversation

@konstin
Copy link
Member

@konstin konstin commented Feb 18, 2026

I noticed that installing a tool in a uv docker image warns by default:

$ docker run --rm -it ghcr.io/astral-sh/uv:debian uv tool install black
Resolved 7 packages in 55ms
Prepared 7 packages in 56ms
Installed 7 packages in 4ms
 + black==26.1.0
 + click==8.3.1
 + mypy-extensions==1.1.0
 + packaging==26.0
 + pathspec==1.0.4
 + platformdirs==4.9.2
 + pytokens==0.4.1
Installed 2 executables: black, blackd
warning: `/root/.local/bin` is not on your PATH. To use installed tools, add the directory to your PATH.

All docker containers have HOME defined, so we can expand PATH with the tool directory

docker run --rm alpine:3.22 sh -c 'echo alpine:3.22 $HOME $PATH'
docker run --rm debian:trixie-slim sh -c 'echo debian:trixie-slim $HOME $PATH'
docker run --rm buildpack-deps:trixie sh -c 'echo buildpack-deps:trixie $HOME $PATH'
docker run --rm python:3.14-alpine3.23 sh -c 'echo python:3.14-alpine3.23 $HOME $PATH'
docker run --rm python:3.13-alpine3.23 sh -c 'echo python:3.13-alpine3.23 $HOME $PATH'
docker run --rm python:3.12-alpine3.23 sh -c 'echo python:3.12-alpine3.23 $HOME $PATH'
docker run --rm python:3.11-alpine3.23 sh -c 'echo python:3.11-alpine3.23 $HOME $PATH'
docker run --rm python:3.10-alpine3.23 sh -c 'echo python:3.10-alpine3.23 $HOME $PATH'
docker run --rm python:3.9-alpine3.22 sh -c 'echo python:3.9-alpine3.22 $HOME $PATH'
docker run --rm python:3.14-trixie sh -c 'echo python:3.14-trixie $HOME $PATH'
docker run --rm python:3.13-trixie sh -c 'echo python:3.13-trixie $HOME $PATH'
docker run --rm python:3.12-trixie sh -c 'echo python:3.12-trixie $HOME $PATH'
docker run --rm python:3.11-trixie sh -c 'echo python:3.11-trixie $HOME $PATH'
docker run --rm python:3.10-trixie sh -c 'echo python:3.10-trixie $HOME $PATH'
docker run --rm python:3.9-trixie sh -c 'echo python:3.9-trixie $HOME $PATH'
docker run --rm python:3.14-slim-trixie sh -c 'echo python:3.14-slim-trixie $HOME $PATH'
docker run --rm python:3.13-slim-trixie sh -c 'echo python:3.13-slim-trixie $HOME $PATH'
docker run --rm python:3.12-slim-trixie sh -c 'echo python:3.12-slim-trixie $HOME $PATH'
docker run --rm python:3.11-slim-trixie sh -c 'echo python:3.11-slim-trixie $HOME $PATH'
docker run --rm python:3.10-slim-trixie sh -c 'echo python:3.10-slim-trixie $HOME $PATH'
docker run --rm python:3.9-slim-trixie sh -c 'echo python:3.9-slim-trixie $HOME $PATH'
alpine:3.23 /root /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
alpine:3.22 /root /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
debian:trixie-slim /root /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
buildpack-deps:trixie /root /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.14-alpine3.23 /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.13-alpine3.23 /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.12-alpine3.23 /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.11-alpine3.23 /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.10-alpine3.23 /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.9-alpine3.22 /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.14-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.13-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.12-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.11-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.10-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.9-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.14-slim-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.13-slim-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.12-slim-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.11-slim-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.10-slim-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.9-slim-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

Test Plan We don't seem to have a standard way to build and test the images locally.

I noticed that installing a tool in a uv docker image warns by default:

```
$ docker run --rm -it ghcr.io/astral-sh/uv:debian uv tool install black
Resolved 7 packages in 55ms
Prepared 7 packages in 56ms
Installed 7 packages in 4ms
 + black==26.1.0
 + click==8.3.1
 + mypy-extensions==1.1.0
 + packaging==26.0
 + pathspec==1.0.4
 + platformdirs==4.9.2
 + pytokens==0.4.1
Installed 2 executables: black, blackd
warning: `/root/.local/bin` is not on your PATH. To use installed tools, add the directory to your PATH.
```

All docker containers have `HOME` defined, so we can expand `PATH` with the tool directory

```
docker run --rm alpine:3.22 sh -c 'echo alpine:3.22 $HOME $PATH'
docker run --rm debian:trixie-slim sh -c 'echo debian:trixie-slim $HOME $PATH'
docker run --rm buildpack-deps:trixie sh -c 'echo buildpack-deps:trixie $HOME $PATH'
docker run --rm python:3.14-alpine3.23 sh -c 'echo python:3.14-alpine3.23 $HOME $PATH'
docker run --rm python:3.13-alpine3.23 sh -c 'echo python:3.13-alpine3.23 $HOME $PATH'
docker run --rm python:3.12-alpine3.23 sh -c 'echo python:3.12-alpine3.23 $HOME $PATH'
docker run --rm python:3.11-alpine3.23 sh -c 'echo python:3.11-alpine3.23 $HOME $PATH'
docker run --rm python:3.10-alpine3.23 sh -c 'echo python:3.10-alpine3.23 $HOME $PATH'
docker run --rm python:3.9-alpine3.22 sh -c 'echo python:3.9-alpine3.22 $HOME $PATH'
docker run --rm python:3.14-trixie sh -c 'echo python:3.14-trixie $HOME $PATH'
docker run --rm python:3.13-trixie sh -c 'echo python:3.13-trixie $HOME $PATH'
docker run --rm python:3.12-trixie sh -c 'echo python:3.12-trixie $HOME $PATH'
docker run --rm python:3.11-trixie sh -c 'echo python:3.11-trixie $HOME $PATH'
docker run --rm python:3.10-trixie sh -c 'echo python:3.10-trixie $HOME $PATH'
docker run --rm python:3.9-trixie sh -c 'echo python:3.9-trixie $HOME $PATH'
docker run --rm python:3.14-slim-trixie sh -c 'echo python:3.14-slim-trixie $HOME $PATH'
docker run --rm python:3.13-slim-trixie sh -c 'echo python:3.13-slim-trixie $HOME $PATH'
docker run --rm python:3.12-slim-trixie sh -c 'echo python:3.12-slim-trixie $HOME $PATH'
docker run --rm python:3.11-slim-trixie sh -c 'echo python:3.11-slim-trixie $HOME $PATH'
docker run --rm python:3.10-slim-trixie sh -c 'echo python:3.10-slim-trixie $HOME $PATH'
docker run --rm python:3.9-slim-trixie sh -c 'echo python:3.9-slim-trixie $HOME $PATH'
```

```
alpine:3.23 /root /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
alpine:3.22 /root /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
debian:trixie-slim /root /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
buildpack-deps:trixie /root /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.14-alpine3.23 /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.13-alpine3.23 /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.12-alpine3.23 /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.11-alpine3.23 /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.10-alpine3.23 /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.9-alpine3.22 /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.14-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.13-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.12-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.11-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.10-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.9-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.14-slim-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.13-slim-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.12-slim-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.11-slim-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.10-slim-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
python:3.9-slim-trixie /root /usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
```

**Test Plan** We don't seem to have a standard way to build and test the images locally.
@konstin konstin requested review from samypr100 and zanieb February 18, 2026 09:18
@konstin konstin added the enhancement New feature or improvement to existing functionality label Feb 18, 2026
@zanieb
Copy link
Member

zanieb commented Feb 18, 2026

I feel like this has come up before? @samypr100 may remember better

@zanieb
Copy link
Member

zanieb commented Feb 18, 2026

See #13057

@zanieb
Copy link
Member

zanieb commented Feb 18, 2026

and #13391

@konstin
Copy link
Member Author

konstin commented Feb 18, 2026

Thanks for digging those up! Maybe the warning is wrong, or UV_TOOL_BIN_DIR is not being respected.

@konstin
Copy link
Member Author

konstin commented Feb 18, 2026

Fixed by an image refresh -.-

@konstin konstin closed this Feb 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or improvement to existing functionality

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants