How to reinstall a broken package? (`--reinstall` and similar have no effect)

[turbotimon]

Question

I'm stuck refreshing a broken package. What do I not understand?

How to reproduce:

1. Create a working project (with pip as an example package)

$ uv init
$ uv add pip
# confirm is not broken
$ uv run -m pip --version
pip 25.1.1 from /home/uv_reinstall/.venv/lib/python3.12/site-packages/pip (python 3.12)

2. Break the package

$ echo "i'm broken" >> /home/uv_reinstall/.venv/lib/python3.12/site-packages/pip/__main__.py
$ uv run -m pip --version
...
File "/home/uv_reinstall/.venv/lib/python3.12/site-packages/pip/__main__.py", line 25
    i'm broken
     ^
SyntaxError: unterminated string literal (detected at line 25)

3. How do completely reinstall it? None of my attempts work, e.g.

$ uv run --reinstall-package pip --refresh-package pip -m pip --version
...
File "/home/uv_reinstall/.venv/lib/python3.12/site-packages/pip/__main__.py", line 25
    i'm broken
     ^
SyntaxError: unterminated string literal (detected at line 25)

$ uv pip uninstall pip
$ uv sync --reinstall
$ uv run -m pip --version
...
File "/home/uv_reinstall/.venv/lib/python3.12/site-packages/pip/__main__.py", line 25
    i'm broken
     ^
SyntaxError: unterminated string literal (detected at line 25)

It seems even the cache is broken ..

$ rm -r .venv/
$ uv sync
Creating virtual environment at: .venv
Resolved 2 packages in 0.68ms
Installed 1 package in 7ms
 + pip==25.1.1
$ uv run -m pip --version
...
File "/home/uv_reinstall/.venv/lib/python3.12/site-packages/pip/__main__.py", line 25
    i'm broken
     ^
SyntaxError: unterminated string literal (detected at line 25)

Platform

Linux 6.12.35 x86_64 GNU/Linux
(NixOS 25.05)

Version

uv 0.7.16 / uv 0.7.19

[turbotimon]

A uv clean helps, but then I do not understand the purpose of --reinstall --refresh and similar options

[konstin]

For your cache, you need uv cache clean -p <package>, --reinstall and --refresh have two different jobs:

uv by default hard-links packages from the cache to the venv. The --reinstall option reinstalls the package into the venv, but if the package got changed in the cache (due to the hard-linking), it reinstalls the changed file again.

By default, uv caches responses from an index (respecting the index' cache headers). With the --refresh option, uv will re-check the index, e.g. if there's a new version on the index.

[turbotimon]

So a what

--reinstall, --force-reinstall
Reinstall all packages, regardless of whether they're already installed. Implies --refresh

does is "just" recreating the hard link? I which situation would that be helpful (honest question)?

And is there no option for the project (run, add, sync) or pip commands to truly reinstall (including redownload) a package? Maybe --no-cache?

[turbotimon]

Also, this sentence from the cache documentation would therefore be wrong in my opinion. Because it does not ignore existing installed versions or isn't it?

If you're running into caching issues, uv includes a few escape hatches:

• To force uv to ignore existing installed versions, pass --reinstall to any installation command (e.g., uv sync --reinstall or uv pip install --reinstall ...).

[turbotimon]

uv add --reinstall --link-mode copy --no-cache pip would at least repair the current venv, but the cache is still broken. So any other project using the same package (and version etc.) would be broken from the beginning..

[turbotimon]

@konstin by the way,-p <package> is not a valid option, instead use just the package name uv cache clean [package]

[charliermarsh]

Yeah, I think you need uv cache clean. I can amend the docs a bit.

I which situation would that be helpful (honest question)?

An example would be if you're working in a virtual environment in which pip installed a given package, and you want to reinstall it with uv.