# uv 工作流程筆記 > 適用於 Python 專案：版本管理、虛擬環境、套件依賴、工具執行。 > 使用 Homebrew 安裝 uv。 Ref. : 1. [官方文件](https://docs.astral.sh/uv/guides/projects/) 2. ChatGPT 整理 ## 1. 安裝 uv ```bash # macOS 使用 Homebrew 安裝 brew install uv # 安裝 uv 管理工具 # 驗證已安裝 uv --version ``` ## 2. 管理 Python 版本 ```bash # 安裝特定版本 uv python install 3.11 3.12 # 安裝 Python 3.11 和 3.12 # 設定預設版本（可選） uv python install --default 3.12 # 列出可用與已安裝版本 uv python list # 列出套件的依賴關係 uv tree ``` ## 3. 建立或啟用虛擬環境 ```bash # 在專案目錄中建立 .venv 虛擬環境 uv venv # 指定 Python 版本 uv venv --python 3.11 # 啟用環境（macOS／Linux） source .venv/bin/activate # 停用環境 deactivate ``` ## 4. 安裝／移除依賴 ```bash # 安裝依賴 uv pip install pandas numpy scikit‑learn # 安裝更多套件 uv pip install matplotlib xgboost shap # 移除依賴 uv pip uninstall shap ``` ## 5. 鎖定／同步環境 ```bash # 根據目前安裝的依賴生成鎖定檔 uv lock # 根據鎖定檔同步安裝正確版本 uv pip sync ``` ## 6. 執行腳本或工具 ```bash # 在虛擬環境中執行腳本 uv run python main.py # 執行臨時工具（不加入專案依賴） uvx pycowsay "hello world" ``` ## 7. 安裝／管理 CLI 工具 ```bash # 安裝工具到持久位置（如 linter） uv tool install ruff # 升級工具 uv tool upgrade ruff ``` ## 8. 專案初始化／發佈（可選） ```bash # 初始化新專案（建立目錄 +設定檔） uv init my‑project # 建構並發佈專案（如發佈至 PyPI） uv build uv publish ``` ## 🔍 小技巧／注意事項 - 建議將虛擬環境放在專案目錄內（如 `.venv`），便於隔離與版本控制。 - 將鎖定檔 (`uv.lock` 或其他) 提交至版本控制系統，確保團隊／機器之間環境一致。 - 若只是快速執行工具而不想污染專案依賴，用 `uvx` 比直接 `pip` 安裝更乾淨。 - 安裝 uv via Homebrew 後，可能需要手動更新 `PATH`，可用 `uv tool update-shell` 幫助（視環境而定）。 - 若專案中已有 `pyproject.toml` 或 `.python-version` 指定 Python 版本，uv 可自動對應管理。 - uv 整合多項功能（版本管理、環境、依賴、工具）— 一次學習可減少多工具切換成本。