uv Python 版本與環境管理

在 Windows 環境以 uv 取代 pip + venv + pyenv 的完整工作流：安裝 Python、建立虛擬環境、管理依賴、鎖定版本，以及協作者一鍵還原環境。

概述

uv 是 Astral 開發的 Python 套件與版本管理工具，以 Rust 撰寫，速度遠快於傳統工具鏈。其核心優勢是整合多個角色：

傳統工具	uv 等效能力
pyenv	uv python install / pin
venv / virtualenv	uv venv / uv run（自動建立）
pip	uv add / uv pip install
pip-compile / poetry.lock	uv.lock

uv 管理的 Python 是獨立安裝，不會污染系統 PATH；--default 與 uv python pin 是兩套獨立機制。

uv 也是 Claude Desktop Extension（MCPB）的推薦執行器——在 mcp_config.command 填入 "uv"，安裝時自動下載 Python 與依賴（詳見Claude Desktop Extension（MCPB）打包與發布）。

核心內容

--default vs uv python pin 的差異

這是初學者最容易混淆的兩套機制：

機制	控制範圍	寫入位置	用途
uv python install --default	直接打 python 時使用的版本	系統 PATH	全域指令 python script.py
uv python pin 3.12	uv run 時使用的版本	.python-version 檔案	專案層級鎖定

在同一目錄下，python --version 和 uv run python --version 可能回傳不同版本，這是正常行為。

版本優先順序

uv run 讀取 Python 版本時，遵循以下優先序（由高到低）：

1. pyproject.toml 的 requires-python
2. 目前目錄的 .python-version
3. 上層目錄的 .python-version（向上遞迴，最終到 $HOME）
4. uv 自行選擇的最新穩定版

核心版控檔案

檔案	用途
pyproject.toml	宣告直接依賴與版本範圍
uv.lock	鎖定所有依賴（含間接依賴）的精確版本
.python-version	指定專案 Python 版本

三個檔案都應加入 Git；.venv/ 加入 .gitignore。

關鍵要點

• uv sync 一條指令完成：安裝對應 Python + 建立 .venv + 安裝所有鎖定依賴
• 通常不需要手動 activate 虛擬環境，直接用 uv run <command> 即可
• uv add 同時更新 pyproject.toml 和 uv.lock，是新增依賴的標準方式
• uv pip install 仍可用，但不更新 pyproject.toml（不推薦用於正式專案）
• uv export --format requirements-txt 可產生傳統 requirements.txt，供 Docker 或不用 uv 的協作者使用

實際應用

協作者還原環境：

git clone <repo>
cd <project>
uv sync
# 完成：Python 版本正確，所有依賴已安裝

在 MCPB extension 中使用（無需使用者手動操作）：

Claude Desktop 安裝 extension 時，uv run --project ${__dirname} 自動觸發依賴下載，使用者無需預裝 Python 或 pip。

部署設定參考

安裝 uv（Windows）

# 官方安裝腳本（PowerShell）
irm https://astral.sh/uv/install.ps1 | iex

# 安裝後重開 terminal
uv --version

# 替代方案
winget install astral-sh.uv
# 或
scoop install uv

安裝 uv（Ubuntu / Linux）

Standalone installer（推薦）：不需預裝 Python 或其他套件管理器，二進位安裝至 ~/.local/bin，並自動更新 shell profile（~/.bashrc 等）。

# curl
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或 wget
wget -qO- https://astral.sh/uv/install.sh | sh

# 安裝後重新載入 shell
source ~/.bashrc   # 或 source ~/.zshrc / 重開 terminal
uv --version

不想讓安裝腳本修改 shell profile 時：

curl -LsSf https://astral.sh/uv/install.sh | env UV_NO_MODIFY_PATH=1 sh
# 之後需手動將 ~/.local/bin 加入 PATH

Homebrew（已安裝 Homebrew 時）：

brew install uv

Snap：

sudo snap install astral-uv --classic

pip / pipx（不推薦用於正式環境）：

pipx install uv
# 或
pip install uv

升級 uv 本身

升級方式取決於安裝方式：

安裝方式	升級指令	適用平台	備註
Standalone installer（官方腳本）	uv self update	Windows、Linux	推薦；自動下載最新版
winget	winget upgrade astral-sh.uv	Windows	—
scoop	scoop update uv	Windows	—
Homebrew	brew upgrade uv	macOS、Linux	—
snap	sudo snap refresh astral-uv	Linux	—
pip	pip install --upgrade uv	跨平台	不支援 uv self update

重要：以 standalone installer 安裝的 uv 才能使用 uv self update；透過其他套件管理器安裝時，此指令不可用，必須改用對應的套件管理器升級。

# Standalone installer 升級（Windows，最常見情況）
uv self update

# winget 升級
winget upgrade astral-sh.uv

# scoop 升級
scoop update uv

# Standalone installer 升級（Linux）
uv self update

# Homebrew 升級
brew upgrade uv

# snap 升級
sudo snap refresh astral-uv

注意：uv self update 執行時會重新跑安裝腳本，可能修改 shell 設定檔（PATH 等）。若不想讓它修改：Windows 執行前設定 $env:UV_NO_MODIFY_PATH = "1"；Linux/macOS 在指令前加 UV_NO_MODIFY_PATH=1 uv self update。

Python 版本管理

# 安裝多個版本
uv python install 3.12 3.13

# 查看已安裝版本
uv python list

# 移除版本
uv python uninstall 3.11

# 註冊 python 全域指令（讓 `python` 指令可用）
uv python install 3.12 --default

# 切換全域版本（直接覆蓋）
uv python install 3.13 --default

Python 版本鎖定

# 全域預設（home 目錄，作為所有專案的 fallback）
cd $HOME
uv python pin 3.12

# 專案層級（覆蓋全域設定）
cd C:\Projects\my-app
uv python pin 3.13

建立虛擬環境與專案

# 全新專案（推薦）
cd C:\Projects
uv init my-app --python 3.13
cd my-app
# 自動產生 pyproject.toml, .python-version
# 首次 uv run 或 uv sync 時自動建立 .venv

# 既有專案（手動建立 venv）
cd C:\Projects\existing-app
uv venv --python 3.12

# 手動啟用（通常不需要）
.venv\Scripts\activate

依賴管理

# 新增依賴（更新 pyproject.toml + uv.lock）
uv add requests fastapi uvicorn

# 新增開發用依賴
uv add --dev pytest ruff mypy

# 從既有 requirements.txt 安裝
uv pip install -r requirements.txt

# 同步環境（確保 .venv 與宣告一致）
uv sync

pip vs uv 指令對照表

環境初始化

功能	pip / venv	uv
建立虛擬環境	python -m venv .venv	uv venv
指定版本建立環境	python3.11 -m venv .venv	uv venv --python 3.11
初始化新專案（含 pyproject.toml）	(手動)	uv init

套件安裝

功能	pip	uv
安裝套件	pip install requests	uv add requests
安裝指定版本	pip install requests==2.31.0	uv add requests==2.31.0
安裝開發用依賴	pip install pytest (手動分類)	uv add --dev pytest
從 requirements.txt 安裝	pip install -r requirements.txt	uv pip install -r requirements.txt
安裝 extras	pip install "fastapi[all]"	uv add "fastapi[all]"
安裝本地套件（可編輯）	pip install -e .	uv pip install -e . 或 uv add --editable .
同步所有依賴（含 lock file）	(無對等)	uv sync

套件移除與更新

功能	pip	uv
移除套件	pip uninstall requests	uv remove requests
更新單一套件	pip install --upgrade requests	uv add --upgrade requests
更新所有套件	pip list --outdated + 手動	uv lock --upgrade 然後 uv sync
更新 lock file（不安裝）	(無對等)	uv lock --upgrade

套件查詢

功能	pip	uv
列出已安裝套件	pip list	uv pip list
查看套件詳細資訊	pip show requests	uv pip show requests
列出過時套件	pip list --outdated	uv pip list --outdated
檢查依賴衝突	pip check	uv pip check

匯出依賴

功能	pip	uv
匯出 requirements.txt	pip freeze > requirements.txt	uv pip freeze > requirements.txt
產生鎖定檔	(需 pip-tools) pip-compile	uv lock
從 pyproject.toml 匯出 requirements	(需 pip-tools)	uv export --format requirements-txt

執行指令（不需啟動 venv）

功能	pip	uv
在專案環境執行指令	(需先 activate)	uv run python script.py
執行模組	(需先 activate)	uv run python -m pytest
臨時安裝並執行工具	pipx run black	uvx black

pip install 全域旗標對照

pip 旗標	uv 對應方式
--no-deps	uv pip install --no-deps
--pre（允許預覽版）	uv add --prerelease=allow
--index-url	uv pip install --index-url <URL>
--extra-index-url	uv pip install --extra-index-url <URL>
--trusted-host	uv pip install --trusted-host <HOST>
--no-cache-dir	uv pip install --no-cache
--quiet	uv --quiet ...
--verbose	uv --verbose ...

重要區別：uv add / uv remove 同時更新 pyproject.toml 與 uv.lock，適合專案管理；uv pip install / uv pip uninstall 是低階指令，行為接近原始 pip，不會更新 pyproject.toml。

Git 版控

# 加入版控
git add pyproject.toml uv.lock .python-version
git commit -m "chore: init project dependencies"

.gitignore 加入：

.venv/

產生傳統 requirements.txt（給 Docker 或不用 uv 的協作者）：

uv export --format requirements-txt > requirements.txt

協作者還原流程

# clone repo 後
uv sync
# 自動：安裝正確 Python → 建立 .venv → 安裝所有鎖定依賴

相關概念

• Claude Desktop Extension（MCPB）打包與發布 — 以 uv 作為 MCPB extension 執行器的實際用例
• WSL 2 安裝指南（Windows 11） — WSL Ubuntu 環境中同樣可使用 uv 管理 Python
• WSL2 Terminal 美化與功能強化 — WSL2 內終端強化後可提升 uv 日常操作效率
• Volta Node.js 版本管理 — 多語言專案中與 uv 並行管理 Node.js 與 Python 版本

來源

• 原始素材：Windows 環境使用 uv 管理 Python 完整指南
• 原始素材：uv 取代 pip 指令對照表