# uv

Python 套件管理神器：`uv`

[參考資料](https://dev.to/codemee/shi-yong-uv-guan-li-python-huan-jing-53hg)

`uv` 是一套包含所有環境管理功能的套件，一般來說 `conda` 可能管理環境，`poetry` 管理純 python 專案，但 `uv` 一次包辦以上！

### 安裝（建議別透過`pip`）

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
$env:Path = "C:\Users\User\.local\bin;$env:Path"

### 使用 uv 替代 python/pip 工具

- `uv run <file_path>`：原本跑程式會用 `python <file_path>`，現在可改用此命令，`uv` 會自己依照以下順序尋找可執行的 Python 環境，而不需手動啟動
- 目前資料夾下的 .python-version 檔內設定的版本。
- 目前啟用的虛擬環境。
- 目前資料夾下的 .venv 資料夾內設定的虛擬環境。
- uv 自己安裝的 Python。
- 系統環境變數設定的 Python 環境。

### 管理虛擬環境與套件

- `uv venv`：建立虛擬環境，`uv` 預設都是使用 `venv` 這個名稱，並且將虛擬環境建立在當前資料夾的 `.venv` 資料夾下。
- 可以在後面接上 `--python 3.10` 來指定虛擬環境的 Python 版本
- 建立完成後 `uv` 都會自動以當前資料夾的虛擬環境執行
- 要刪除虛擬環境就直接刪 `.venv` 資料夾就好
- `uv pip install <package>`：`uv pip` 提供與 `pip` 相容的介面管理套件
- 比原生的 `pip` 快上許多
- 但刪除套件時 `uv pip uninstall` 不會自行刪除依賴項
- `uv tool install <package>`：全域安裝，獨立於專案之外
- 通常是安裝全域 CLI：`black`、`ruff`、`httpie`、`pre-commit`、`poetry`
- 安裝的工具在任何資料夾都可使用
- 可以用 `uv tool upgrade` 或 `uv tool uninstall` 來升級或移除
- 在 VScode 裡面要選定 Python 的編譯器，這時候點選右下角，改用瀏覽的方式選取 `./.venv/Scripts/python.exe`，也就是當前虛擬環境裡的 Python 執行檔，就可以讓語法上色了。

### 管理專案

- `uv init`：初始化一個 uv 專案，包含 `.gitignore`, `.python-version`, `pyproject.toml` 等
- `uv add <package>`：專案內用這個命令來安裝套件
- 會紀錄依賴關係，並修改於 `pyproject.toml`
- 會更新或建立 `uv.lock` 來鎖定版本以重現（不需手動修改）
- 會安裝到專案的虛擬環境 `.venv`
- `uv pip install .`：從寫好的 `pyproject.toml` 安裝全部
- `uv tree`：可以看到套件的相依關係
- `uv remove <package>`：和 `uv add` 是反向操作
- 一樣會更新 `pyproject.toml`, `uv.lock`, `.venv`
- 會將指定套件、不再需要的相關依賴套件也一併刪除
- `uv lock --upgrade`：更新所有套件
- `uv lock --upgrade-package <package>` ：更新指定套件
- `uv run <套件提供的命令> ...`：指定 uv 環境跑檔案

### 手動修改專案、同步專案、跑別人的專案

#### uv 原生流程

1. （可選）先更改 `pyproject.toml` 的內容（刪除或新增套件）
3. `uv lock`：修改 `uv.lock` 檔案內容
4. `uv sync`：真正將修改後的 `uv.lock` 同步到虛擬環境

:::success
即使已經 `uv sync`，還是可以繼續用 `uv add <package>`，會自動執行上述三項動作。
:::

#### uv 提供的 pip 流程

1. `uv export --no-hashes --format requirements-txt -o requirements.txt`：從 `uv.lock` 匯出套件與版本，通常是最準確的方法。
3. `uv pip compile -o requirements.txt`：從 `pyproject.toml` 先編譯出鎖定檔（就是 `requirements.txt`）並將所有套件的版本寫入至鎖定檔
4. `uv pip sync`：用來找 `requirements.txt` 並安裝
### 啟動 / 關閉虛擬環境

- `.venv\Scripts\activate`：用這行指令啟動環境，才能用環境裡的套件
- `deactivate`：用這行指令關閉虛擬環境