Python - UV

GitHub - astral-sh/uv: An extremely fast Python package and project manager, written in Rust.

uv init
uv python install 3.12
uv venv --python 3.12
uv add numpy

source .venv/bin/activate

# 可以用於 jupyter
uv add jupyter ipykernel 
uv run python -m ipykernel install --user --name uv_kernel --display-name "uv: uv_kernel"
uv run jupyter lab

說明：uv 封裝 venv/pip，負責新增/移除相依、環境同步、在隔離環境執行指令。

uv venv .venv
source .venv/bin/activate

初始化專案

uv init --package      # 產生最小化 pyproject.toml；可直接 add 相依
# 或在既有專案內使用：直接 uv add（會自動偵測/建立 .venv）

加入相依（你）

uv add flask                 # 新增直接相依，並安裝到專案專屬 .venv
uv add "pydantic>=2,<3"      # 指定版本範圍
uv add "fastapi[standard]"   # 安裝 extra
uv add --dev pytest mypy     # 新增開發相依（測試、型別檢查）
uv remove flask              # 乾淨移除並更新設定

環境同步（其他協作者）

uv sync            # 依據 pyproject.toml（與鎖檔，如存在）重建 .venv
uv sync --no-dev   # 只裝「執行時」相依（部署情境）
uv sync --frozen   # 嚴格依鎖檔版本（CI/生產）

在隔離環境執行（免手動啟動 .venv）

uv run main.py          # 執行 Python 腳本
uv run python -V        # 執行任意命令（這裡是查版本）
uv run pytest -q        # 跑測試
uv run mypy .           # 型別檢查

可編輯安裝（本專案做為套件開發）

uv add -e .             # 等同 pip install -e .，不拷貝原始碼，指向工作目錄

輸出/鎖定（可選，用於部署/CI）

uv lock                 # 產生或更新相依鎖定（若使用鎖檔流程）
uv export -o requirements.txt   # 需要傳統 requirements.txt 時匯出快照

Python 版本與環境（可選）

uv python install 3.11          # 安裝指定 Python（缺版本時很實用）
uv venv                          # 建立/管理專案虛擬環境

日常檢查與除錯（實用）

uv tree                # 檢視相依樹（找出誰拉進了哪個版本）
uv pip list            # 查看安裝結果（與 pip 類似的檢視）

小訣竅：

變更相依後，團隊側只需 uv sync 即可重現同一環境。
部署/CI 建議搭配 uv sync --frozen 確保版本完全一致。
出現版本衝突時，用 uv tree 先看誰相依了衝突版本再調整範圍。

最小工作流程（你 → 其他人）

說明：一人建立、多人協作的最短路徑。

你（作者）

uv init --package
uv add flask
uv run main.py
git add pyproject.toml  # 連同程式碼入版控
git commit -m "init with flask"

其他使用者（協作者）

git clone <repo> && cd <repo>
uv sync
uv run main.py

常見問題（快速定位）

說明：最常見的坑與對策。

執行抓到全域套件 → 一律用 uv run <cmd> 或先 uv sync；which python 檢查路徑
移除套件仍殘留傳遞相依 → 用 uv remove <pkg>，並 uv sync 讓解算器清乾淨
IDE 沒抓到環境 → 專案內資料夾命名 .venv，VSCode/PyCharm 會自動辨識