Python 套件管理工具 uv 和 pip 的快取

Python 使用套件管理工具 uv 和 pip 安裝套件時，預設會在本地保存快取，之後安裝到相同套件，則不用再次下載，若已用不到快取，可刪除快取釋放空間。
Caching - pip documentation：https://pip.pypa.io/en/stable/topics/caching/

Caching | uv：https://docs.astral.sh/uv/concepts/cache/

注意：

uv 安裝套件時，使用檔案硬連結(Hard Link)增快安裝速度、節省硬碟空間，如果出現以下 warning 訊息，代表目前磁碟分割區跟 uv 快取資料夾所在磁碟區不同，因為硬連結不能跨磁碟區，所以改用複製檔案的方式安裝。

參考： Failed to hardlink files: Issue with ruff cache · Issue #7285 · astral-sh/uv

warning: Failed to hardlink files; falling back to full copy. This may lead to degraded performance.
         If the cache and target directories are on different filesystems, hardlinking may not be supported.
         If this is intentional, set `export UV_LINK_MODE=copy` or use `--link-mode=copy` to suppress this warning.

如何判斷一個檔案是不是硬連結？

可使用 fsutil hardlink list 指令列出指定檔案的所有硬連結，如果只有一筆資料，代表該檔案是唯一一個。

fsutil hardlink list 檔案路徑

uv 快取資料夾在C磁碟區，所以在D磁碟區安裝的套件檔案，是自己一個佔一個儲存空間。
後面指令執行結果，只列出1資料。

>fsutil hardlink list d:\00\.venv\Lib\site-packages\ruff\_find_ruff.py
\00\.venv\Lib\site-packages\ruff\_find_ruff.py

uv 快取資料夾在C磁碟區，所以在C磁碟區安裝的套件檔案，是多個檔案佔一個儲存空間。
後面指令執行結果，列出4資料，可知是4個檔案只占了一個儲存空間的硬連結。

>fsutil hardlink list C:\00\b\.venv\Lib\site-packages\ruff\_find_ruff.py
\Users\xyz\AppData\Local\uv\cache\archive-v0\PlO16jmvtBvGz4Q-TOodW\ruff\_find_ruff.py
\00\a\.venv\Lib\site-packages\ruff\_find_ruff.py
\Users\xyz\AppData\Roaming\uv\tools\ruff\Lib\site-packages\ruff\_find_ruff.py
\00\b\.venv\Lib\site-packages\ruff\_find_ruff.py

專案跟 uv 預設快取資料夾不同磁碟區，如何修改 uv 快取資料夾位置？

三種方式：(後面例子將快取資料夾設定為 D:\uvCache)

1. 指令安裝套件時，設定 --cache-dir 參數值，指定快取資料夾。
   

   uv pip install 套件名稱 --cache-dir D:\uvCache

2. 設定 UV_CACHE_DIR 環境變數，指定快取資料夾。
   注意若使用 setx 指令設定永久環境變數，有長度1024 限制，超過會自動截斷，設定值如果有變數，長度計算需看變數代表的內容長度。
   參考：https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/setx?WT.mc_id=DOP-MVP-37580#remarks
   (Be aware there's a limit of 1024 characters when assigning contents to a variable using setx. This means that the content is cropped if you go over 1024 characters, and that the cropped text is what's applied to the target variable. If this cropped text is applied to an existing variable, it can result in loss of data previously held by the target variable.)

   setx UV_CACHE_DIR "D:\uvCache"

   setx 設定的環境變數，在新開的終端視窗才會生效，可先 echo %UV_CACHE_DIR% 看一下目前終端的值

   >echo %UV_CACHE_DIR%
   D:\uvCache

3. 在專案資料夾新增 uv 設定檔 uv.toml，指定快取資料夾。
   參考 https://docs.astral.sh/uv/reference/settings/#cache-dir
   uv.toml 檔案內容如後，uv 會在目前目錄或最近的父目錄中尋找 pyproject.toml、uv.toml 檔案。
   

   cache-dir = 'D:\uvCache'

pip 與 uv 快取相關指令：

	pip	uv
版本	> py -m pip -V pip 24.3.1 from C:\Users\xyz\AppData\Local\Programs\Python\Python313\Lib\site-packages\pip (python 3.13)	> uv version uv 0.5.27 (73e9928d4 2025-02-03)
查看快取資料夾路徑	> py -m pip cache dir c:\users\xyz\appdata\local\pip\cache	> uv cache dir C:\Users\xyz\AppData\Local\uv\cache 預設路徑  macOS and Linux：`$XDG_CACHE_HOME/uv` 或 `$HOME/.cache/uv` Windows： `%LOCALAPPDATA%\uv\cache`
快取資訊	> py -m pip cache info Package index page cache location (pip v23.3+): c:\users\xyz\appdata\local\pip\cache\http-v2 Package index page cache location (older pips): c:\users\xyz\appdata\local\pip\cache\http Package index page cache size: 0 bytes Number of HTTP files: 0 Locally built wheels location: c:\users\xyz\appdata\local\pip\cache\wheels Locally built wheels size: 2.3 kB Number of locally built wheels: 0
快取列表	> py -m pip cache list [<pattern>] [--format=[human, abspath]] <pattern>：glob expression 或 package name > py -m pip cache list No locally built wheels cached.
移除指定快取	> py -m pip cache remove <pattern> <pattern>：glob expression 或 package name > py -m pip cache remove aa WARNING: No matching packages for pattern "aa" Files removed: 0
清除快取	> py -m pip cache purge	> uv cache clean Clearing cache at: AppData\Local\uv\cache Removed 119321 files (5.9GiB) 會刪除整個快取資料夾
刪除沒用到的快取		> uv cache prune Pruning cache at: AppData\Local\uv\cache Removed 272417 files (12.6GiB)
Cache Options	--format <list_format> Select the output format among: human (default) or abspath 相關： 安裝時不保存使用快取 py -m pip install --no-cache-dir <package>	-n, --no-cache Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation [env: UV_NO_CACHE=] --cache-dir <CACHE_DIR> Path to the cache directory. Defaults to `$XDG_CACHE_HOME/uv` or `$HOME/.cache/uv` on macOS and Linux, and `%LOCALAPPDATA%\uv\cache` on Windows. [env: UV_CACHE_DIR=]