---
# System prepended metadata

title: uv 工作流程筆記
tags: [公開, Env, Python]

---

# 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 整合多項功能（版本管理、環境、依賴、工具）— 一次學習可減少多工具切換成本。