Python uv 常見操作模式：依賴、uvx 與腳本執行

這篇聚焦在日常開發最常做的五件事，直接給你可落地的操作範本。練熟這幾招，八成情境都能應付——剩下兩成留給進階篇。

模式一：依賴新增與移除

# 新增依賴
uv add requests
uv add "requests>=2.31,<3"   # 版本約束
 
# 開發依賴（測試、lint、型別檢查）
uv add --dev pytest ruff mypy
 
# 移除
uv remove requests

uv add 會同時更新 pyproject.toml、uv.lock 和 .venv，一鍵到位。

模式二：uv run 執行專案內指令

專案內的腳本、CLI、測試，一律用 uv run：

uv run python main.py
uv run pytest
uv run ruff check .
uv run mypy src/

不用 activate，也不用擔心用錯 Python。

模式三：uvx 執行獨立 CLI 工具

想臨時跑個工具、不想裝進專案？用 uvx（等同 uv tool run）：

# 隨叫隨用，用完即棄
uvx ruff check .
uvx pycowsay "hello uv"
 
# 指定版本
uvx ruff@0.5.0 check
 
# 套件名跟指令不同時
uvx --from httpie http https://httpbin.org/get

uvx 會建一個暫時的環境來跑，不污染專案——像試吃不用買整包，吃完拍拍屁股走人，超適合「我就試一下」的場景。

模式四：腳本內聯依賴（PEP 723）

單一腳本、懶得建專案？用 inline script metadata：

# /// script
# dependencies = ["requests", "rich"]
# ///
 
import requests
from rich.pretty import pprint
 
r = requests.get("https://api.github.com/zen")
pprint(r.text)

uv add --script fetch.py requests rich
uv run fetch.py

或一行搞定：

uv run --with requests --with rich fetch.py

模式五：從 requirements.txt 遷移

既有專案有 requirements.txt？直接吃進去：

uv add -r requirements.txt

或編譯成 lockfile 再同步：

uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt

遷移完記得把 pyproject.toml 當主源，requirements.txt 可以當匯出用。

下一步

日常模式練完，要玩 Python 版本切換、pip 介面或 monorepo 的話：
👉 進階用法