上一篇我們認識了 uv 是什麼、如何安裝。這篇要進入實戰：用 uv 建立虛擬環境、安裝套件、管理依賴檔案。

為什麼需要虛擬環境？

當你用 AI 輔助開發多個專案時，常會遇到這種情況：

• 專案 A 需要 requests==2.28.0
• 專案 B 需要 requests==2.31.0

如果都裝在系統 Python，版本會互相衝突。虛擬環境讓每個專案有獨立的套件空間，互不干擾。

建立虛擬環境：uv venv

基本建立

在專案目錄執行：

uv venv

這會在當前目錄建立 .venv 資料夾，裡面是獨立的 Python 環境。

指定 Python 版本

uv venv --python 3.11
Code language: CSS (css)

這會建立使用 Python 3.11 的虛擬環境。如果系統沒有該版本，uv 會自動下載。

指定資料夾名稱

uv venv my_env

這會建立名為 my_env 的虛擬環境資料夾（預設是 .venv）。

啟用虛擬環境

建立後需要啟用才能使用：

Linux / macOS：

source .venv/bin/activate

Windows：

.venv\Scripts\activate
Code language: CSS (css)

啟用後，終端機提示會顯示 (.venv)，表示你現在在虛擬環境中。

小技巧：uv run 自動使用虛擬環境

其實 uv 有個方便的功能：uv run 會自動偵測並使用當前目錄的 .venv：

uv run python script.py
Code language: CSS (css)

這樣就不用每次手動 activate 了。

安裝套件：uv pip install

安裝單一套件

uv pip install requests

安裝指定版本

uv pip install requests==2.31.0

安裝多個套件

uv pip install requests flask pandas

從 requirements.txt 安裝

這是最常見的情境。當你 clone 一個專案，通常會看到 requirements.txt：

uv pip install -r requirements.txt
Code language: CSS (css)

uv 會讀取檔案內容，一次安裝所有依賴。

升級套件

uv pip install --upgrade requests

移除套件

uv pip uninstall requests

匯出依賴：記錄你裝了什麼

uv pip freeze：匯出已安裝套件

uv pip freeze > requirements.txt
Code language: CSS (css)

這會把目前環境的所有套件（含版本）輸出到檔案。別人拿到這個檔案就能重建相同環境。

輸出範例：

certifi==2024.2.2
charset-normalizer==3.3.2
idna==3.6
requests==2.31.0
urllib3==2.2.0

uv pip compile：鎖定依賴版本

freeze 只是列出已安裝的套件。compile 更進階，它會：

1. 讀取你的 requirements.in（只列主要依賴）
2. 解析所有子依賴
3. 輸出完整的版本鎖定檔

# 建立 requirements.in（你直接需要的套件）
echo "requests" > requirements.in
echo "flask" >> requirements.in

# 編譯成完整的 requirements.txt
uv pip compile requirements.in -o requirements.txt
Code language: CSS (css)

輸出的 requirements.txt 會包含所有子依賴及其精確版本，確保每次安裝結果一致。

同步依賴：uv pip sync

這是 uv 的殺手級功能。sync 會讓環境「完全符合」requirements.txt：

uv pip sync requirements.txt
Code language: CSS (css)

它會：

• 安裝缺少的套件
• 移除多餘的套件
• 調整版本不符的套件

為什麼這很重要？

假設你的 requirements.txt 有 10 個套件，但你之前測試時多裝了 5 個。用 install -r 只會新增，不會移除多餘的。sync 會確保環境「乾淨」，只有需要的套件。

常用指令對照表：pip vs uv pip

重點：uv pip 的指令結構和 pip 幾乎相同，只是前面加上 uv。如果你熟悉 pip，遷移成本很低。

實戰範例：從零建立專案環境

假設你要開始一個新的 Flask 專案：

# 1. 建立專案目錄
mkdir my_flask_app
cd my_flask_app

# 2. 建立虛擬環境（使用 Python 3.11）
uv venv --python 3.11

# 3. 安裝依賴
uv pip install flask python-dotenv

# 4. 匯出依賴檔案
uv pip freeze > requirements.txt

# 5. 執行程式（自動使用 .venv）
uv run python app.py
Code language: CSS (css)

當同事要接手這個專案：

# 1. Clone 專案
git clone <repo_url>
cd my_flask_app

# 2. 建立虛擬環境
uv venv

# 3. 同步依賴（確保環境一致）
uv pip sync requirements.txt

# 4. 開始開發
uv run python app.py
Code language: PHP (php)

常見問題

Q: uv venv 和 python -m venv 有什麼差別？

功能相同，但 uv venv：

• 速度更快
• 可以自動下載指定的 Python 版本
• 不需要先裝好該版本的 Python

Q: 什麼時候用 freeze，什麼時候用 compile？

• freeze：快速記錄目前環境，適合個人專案
• compile：精確鎖定版本，適合團隊協作或部署

Q: 一定要 activate 才能用虛擬環境嗎？

不一定。使用 uv run 可以自動使用 .venv，不需要 activate。

本篇重點回顧

• uv venv：建立虛擬環境，可指定 Python 版本
• uv pip install：安裝套件，語法和 pip 相同
• uv pip freeze：匯出已安裝套件清單
• uv pip compile：從 .in 檔編譯完整依賴
• uv pip sync：同步環境，移除多餘套件
• uv run：自動使用 .venv 執行指令

下一篇我們會介紹 uv 的專案管理功能：pyproject.toml 和 uv.lock，讓依賴管理更現代化。