Conforming to the XDG specification

[NellyWhads]

Currently, uv prioritizes $HOME/... paths over $XDG_* paths in most cases. This behavior is contradictory to the XDG specification.

This means when setting XDG_* variables in a docker image, for example, UV_* variables also must be set.

Examples of variables which do not automatically use the XDG_* specification:

ENV UV_TOOL_DIR="${XDG_STATE_HOME}/uv/tools"
ENV UV_PYTHON_INSTALL_DIR="${XDG_STATE_HOME}/uv/python"
ENV UV_CACHE_DIR="${XDG_CACHE_HOME}/uv"

Example of a UV_* variable mapping to multiple potential XDG_* locations: https://docs.astral.sh/uv/configuration/installer/#changing-the-install-path

Consistent environment inheritance would make uv easier to configure according to the XDG specification.

[charliermarsh]

I think these all respect XDG... The uv cache at least respects XDG_CACHE_HOME. I believe the tool dir also respects XDG_BIN_HOME. And Python respects XDG_DATA_HOME.

[NellyWhads]

I'll try again but was running into path errors unless I explicitly set them in the Dockerfile.

I presume this isn't a recent change - they've been respected for quite some time?

[zanieb]

Yeah I think we've respected XDG-first for quite some time.

[NellyWhads]

Here's the outcome of my testing:

$ env | grep -E "^(XDG|UV)_" && uv cache dir && uv python dir && uv tool dir
XDG_BIN_HOME=/opt/bin
XDG_DATA_HOME=/opt/share
XDG_CONFIG_HOME=/opt/config
XDG_CACHE_HOME=/opt/cache
XDG_STATE_HOME=/opt/state
/opt/cache/uv
/opt/share/uv/python
/opt/share/uv/tools

I tried searching through the uv docs for either a config print-out which can tell the user where each of the UV_* directories are expected to be mapped, or consistent documentation regarding which XDG_* directories will be used for but wasn't able to track something consistent down.

Manually executing tool and python installs leads to these inferred locations:

Tools:

$ uv tool install tldr && whereis tldr
Resolved 4 packages in 49ms
Prepared 4 packages in 15ms
Installed 4 packages in 4ms
 + colorama==0.4.6
 + shtab==1.7.1
 + termcolor==2.5.0
 + tldr==3.3.0
Installed 1 executable: tldr
tldr: /opt/bin/tldr

Python versions:

$ uv python install 3.8 && whereis python3.8
Installed Python 3.8.20 in 1.10s
 + cpython-3.8.20-linux-x86_64-gnu
python3.8:

$ export UV_PYTHON_BIN_DIR=${XDG_BIN_HOME}

$ uv python install 3.10 && whereis python3.10
Installed Python 3.10.16 in 1.14s
 + cpython-3.10.16-linux-x86_64-gnu
python3.10:

$ env | grep -E "^(XDG|UV)_"
UV_PYTHON_BIN_DIR=/opt/bin
XDG_BIN_HOME=/opt/bin
XDG_DATA_HOME=/opt/share
XDG_CONFIG_HOME=/opt/config
XDG_CACHE_HOME=/opt/cache
XDG_STATE_HOME=/opt/state

Could I get some help with the python bin dir configuration? If so, I'd be happy to make a small PR which adds the appropriate references to the environment variables page.

[charliermarsh]

I think these are all documented in the help? Like uv help python dir.

[zanieb]

We don't install Python binaries into the bin directory without --preview, ref #8458

[NellyWhads]

Ah, okay. I have been reading the web documentation here: https://docs.astral.sh/uv/configuration/environment/

The references aren't easily traced in those links.

--preview did indeed fix the python linking - I'll enable that in my docker setup!

[NellyWhads]

Is python bin-linking the only current --preview feature (seems to be the only mention in web docs)? Can we expect more / where can we learn about all --preview features?

[zanieb]

The other preview feature is a build backend. We'll probably talk more about preview features in the documentation in the future, yeah. They're mentioned in the changelog.