Manage all uv-related directories

[Ma-Shell]

Summary

Note: This issue is somewhat related to #6067, especially this comment, mentioning that the UV_PYTHON_INSTALL_DIR option might be exposed to uv.toml, as well as #6506 but extends it to further directories, adds some further reasoning and has a generally wider scope, so I opted for creating a new issue.

UV uses multiple directories. The documentation refers to these 5 but there might be more which I missed.

Directory	command	environment variable	uv.toml/pyproject.toml
cache	uv cache dir	UV_CACHE_DIR	cache-dir
python	uv python dir	UV_PYTHON_INSTALL_DIR	-
python bin	uv python dir --bin	UV_PYTHON_BIN_DIR	-
tools	uv tool dir	UV_TOOL_DIR	-
tools bin	uv tool dir --bin	UV_TOOL_BIN_DIR	-

There are several improvements for managing these:

• Add a command which lists all of them for more transparency with the user
• For the ones, where there is no .toml-entry available, one should be added. This would help especially when using a global uv.toml, to allow to define one base-directory for everything, without relying on environment variables.
• While the documentation mentions that there is a platform-dependent location for a default uv.toml, it would be beneficial to have uv also check the uv-executable's directory for a uv.toml, which again would help with having everything uv-related in one directory.

Example

The proposed features allow having a portable installation giving the user more control about what paths are touched by UV.

Being able to manage the directories in the toml-file without relying on environment variables also helps for having globally installed projects in multi-user environments as the default-locations refer to directories within the user's profile (like %APPDATA% or ~/.local) which are not readable by all users.

[eabase]

This is a great idea and would align better with my proposal of also managing venv's here:
#11773

[mjnd1]

Mark it down. When will it be completed?

[konstin]

Another option here would be an env var named something like UV_DATA_ROOT that, if set, defines a directory where uv creates all of its directories (cache, tools, python interpreter, config) below it.

[LOYINuts]

Yeah we need that desperately. Something like UV_DATA_ROOT will be great

[konstin]

A more concise approach than setting the UV_*_DIR variables is setting the XDG_* variables that uv uses. By controlling XDG_DATA_HOME, XDG_CACHE_HOME, XDG_CONFIG_HOME, and XDG_BIN_HOME, you can control the non-venv files and directories that uv writes.

Variable	Default Path	Description
$XDG_DATA_HOME	$HOME/.local/share	Files written by uv that need to be persisted (tools, python interpreters, etc.)
$XDG_CACHE_HOME	$HOME/.cache	Cache, ephemeral files that can be removed when uv isn't running
$XDG_CONFIG_HOME	$HOME/.config	Where uv finds uv.toml
$XDG_BIN_HOME	$HOME/.local/bin	Binaries uv adds to PATH (uv itself, installed tools, python interpreters)

If that approach works for your use cases, we can add it to the docs. We're also working on a general reference documentation of uv directories (#13976).

[Ma-Shell]

Thank you for the response! While it is certainly a good idea to add this information to the documentation, this issue is mostly about the ability to use the config file instead of environment variables and to automatically use the config file in the executable's directory as a first choice, though.

[LOYINuts]

I mean there are too many variables, just like you mentioned before, one variable like UV_DATA_ROOT will be great and much convenient

[eabase]

For the love of god, please don't default to $HOME/.random for UV configuration files.

Especially not these locations:

$HOME/.local/*
$HOME/.cache
$HOME/.config

These are locations most often used with Nix based tools, like MSYS, Cygwin, WSL etc. or tools that have been ported from there. In those environments they have very specific functions, just like .git and .ssh has. I'm not sure at what point in time Dev's started thinking that these locations were at their own convenient disposal, and freely available for install/bloat. They are not!

If you wanna default, at least put it in your own place.
I strongly suggest using: $HOME/.uv/* instead.

Also, using new environment variables prefixed by XDG_ is very confusing to most users. The variable doesn't say sh-t what it is about and what software it relates to. At least use a UV_ prefix.

[Winand]

using new environment variables prefixed by XDG_ is very confusing to most users

@eabase there's a spec for those X Desktop Group variables (except for XDG_BIN_HOME) XDG Base Directory Specification

[eabase]

@Winand

there's a spec for those X Desktop Group variables...

Which is exactly why you shouldn't mix up UV locations with X Windows!

Remind you that X-Windows has always been a nightmare to configure, and part of the reason why this structure got so messed up in the first place. People rebuilding broken structures based on old habits, because of laziness to rethink and make something more future proof and self contained. (Read the very first comment (from your link) about linking XDG_ vars to MacOS directories. Madness.)

Freedesktop.org is a project to work on interoperability and shared base technology for free-software desktop environments for the X Window System (X11) and Wayland on Linux and other Unix-like operating systems.

So what make you think using X11 variables is a great idea for cross platform use of UV?

I just fail to see any advantage at all, so please fill us in.

IMO users should never have to (or be forced) to think where their customization & settings are located and installed. They should also be safe for cross machine migration and updates.

You're basing your UX ideology from a fringe Linux PoV. The reality is that Python has exploded across all platforms, but most noticeable on Windows. So pushing a mixed file / environment to most non-technical end users, doesn't make sense. And if I was selfish, I would also agree to use the Linux structure, but that is again already broken since long ago. Just google on /opt, /usr/shared/, /usr/local etc etc. and you will get as many different answers as there are nix distros.

---

---

The OP suggestion makes full sense, so why are you trying to derail that suggestion to something else?
(I.e. using completely different variable names, unrelated to UV.)

[konstin]

We chose the XDG_ environment variables as they are the only set of configuration that are already well-known to users and that are supported by a wide range of (CLI) applications. For the default values, when no XDG_ variables are set, we were originally closer to the platform default, but eventually decided to for using a more Linux-style cross-platform for consistency. XDG and the conventions around it map well to the kind of tasks uv does, e.g., Windows does not have a native directory for adding binaries to PATH as non-admin.

(This is kinda separate from the OP about having a portable uv installation with associated uv.toml settings)