`uv tool install --reinstall` not working as documented

[dpoznik]

The docs suggest that uv tool install --reinstall should reinstall all packages:

$ uv --version
uv 0.4.20 (0e1b25a53 2024-10-08)

$ uv tool install --help
...
      --reinstall                              Reinstall all packages, regardless of whether they're already installed. Implies `--refresh`
      --reinstall-package <REINSTALL_PACKAGE>  Reinstall a specific package, regardless of whether it's already installed. Implies `--refresh-package`
...

This suggests that one need not specify a particular package. But in practice, a package name is expected:

$ uv tool install --reinstall
error: the following required arguments were not provided:
  <PACKAGE>

Usage: uv tool install --reinstall --index-url <INDEX_URL> <PACKAGE>

[charliermarsh]

uv tool install --reinstall <PACKAGE> will reinstall <PACKAGE> and all of its dependencies (whereas uv tool --reinstall-package <FOO> <PACKAGE> will reinstall <FOO>, but not <PACKAGE>). Any suggestions on how to make this clearer?

[bluss]

--reinstall is not "Reinstall all tools", but it's like "Reinstall everything for one tool".

Maybe this is a clarification. Here PACKAGE is the tool you want to install:

Usage: uv tool install [OPTIONS] <PACKAGE>

---

But below, packages is all the distribution packages in the installation of the tool (the previous single PACKAGE).

Installer options:
      --reinstall
          Reinstall all packages, regardless of whether they're already installed. Implies
          `--refresh`

[dpoznik]

Any suggestions on how to make this clearer?

Perhaps something like the following, wherein instances of "package" have been edited to forms of "dependency" to disambiguate "packages" providing tools from "packages" these tool-providing packages depend on:

      --reinstall                         Reinstall all dependencies, regardless of whether they're already installed. Implies `--refresh`
      --reinstall-package <DEPENDENCY>    Reinstall a specific dependency, regardless of whether it's already installed. Implies `--refresh-package`

      --refresh                           Refresh all cached data
      --refresh-package <DEPENDENCY>      Refresh cached data for a specific dependency

It may be even clearer if the second and fourth option were --reinstall-dependency and --refresh-dependency, respectively. But that would involve more than just a documentation tweak.

Thanks!

[dpoznik]

Relatedly, does uv tool have an equivalent to pipx's reinstall-all subcommand? I find this useful when, for example, upgrading Python.

[charliermarsh]

You can do uv tool upgrade --all. You can even do uv tool upgrade --all --python 3.13 to upgrade all installed tools to Python 3.13.

[dpoznik]

You can do uv tool upgrade --all. You can even do uv tool upgrade --all --python 3.13 to upgrade all installed tools to Python 3.13.

Ah, so uv tool upgrade is closer in behavior to pipx reinstall than to pipx upgrade, which upgrades a tool within its existing environment. Got it. Thanks!

If not already present, it may be worth noting this contrast somewhere in the docs to help folks transition.

[charliermarsh]

\cc @zanieb for opinions on changing the --reinstall docs.