Python 虛擬環境教學 — uv 專案管理與套件安裝（venv/pip 比較）

Python 虛擬環境（Python Virtual Environment）

這篇 Python 虛擬環境教學將回答兩個問題：為什麼需要虛擬環境？以及怎麼用 uv 把「環境＋套件」一次管好。安裝第三方套件之前，這篇是必修——直接把套件裝進系統 Python 是新手最常見的環境災難來源。

為什麼需要虛擬環境

假設專案 A 需要某套件 1.x 版、專案 B 需要 2.x 版，全裝在系統 Python 裡必定打架。虛擬環境讓每個專案擁有自己獨立的套件空間：

問題	沒有虛擬環境	有虛擬環境
版本衝突	專案間互相干擾	各專案獨立
環境重現	「在我電腦可以跑」	依紀錄一鍵還原
系統污染	系統 Python 越裝越亂	系統保持乾淨

傳統做法 vs uv

傳統流程要自己處理 venv 建立、啟用、pip 安裝、requirements.txt 維護；uv 把這些全包了：

動作	傳統（venv + pip）	uv
建立專案環境	`python -m venv .venv`	`uv init` 後自動處理
啟用環境	`source .venv/bin/activate`	不需要，`uv run` 自動用
安裝套件	`pip install requests`	`uv add requests`
紀錄相依	手動 `pip freeze > requirements.txt`	自動寫入 `pyproject.toml`
還原環境	`pip install -r requirements.txt`	`uv sync`

用 uv 建立專案

uv init myproject
cd myproject

uv 會建立專案骨架，重點檔案：

檔案	用途
`pyproject.toml`	專案設定與相依套件清單
`main.py`	範例進入點
`.venv/`	虛擬環境（第一次執行時自動建立）
`uv.lock`	鎖定每個套件的精確版本

安裝套件：uv add

以安裝 HTTP 套件 requests 為例（第 40 篇會正式使用）：

uv add requests

執行輸出（版本號可能不同）：

Resolved 6 packages in 120ms
Installed 5 packages in 80ms
 + certifi==2026.4.26
 + charset-normalizer==3.4.2
 + idna==3.10
 + requests==2.32.4
 + urllib3==2.4.0

套件同時被記進 pyproject.toml，移除用 uv remove requests。

執行程式：uv run

uv run main.py

uv run 會自動使用專案的虛擬環境，不需要手動啟用，這是 uv 最方便的地方。在專案裡測試套件是否可用：

# main.py
import requests

print(requests.__version__)

uv run main.py

執行輸出（版本號可能不同）：

2.32.4

還原環境：uv sync

拿到別人的專案（或換了電腦）時，一行還原所有相依套件：

uv sync

因為有 uv.lock 鎖定精確版本，裝出來的環境跟原作者完全一致——「在我電腦可以跑」從此有解。

常見錯誤

1. ModuleNotFoundError（裝了卻找不到）

最常見原因：套件裝在別的環境。用 uv 流程時，執行一律用 uv run，就不會用錯環境；混用系統 python 指令就會找不到套件。

2. 把 .venv 傳給別人或進版本控制

.venv 資料夾又大又綁定機器，不要複製、不要 commit（uv 產生的 .gitignore 已排除）。要分享環境，給 pyproject.toml + uv.lock 就夠。

3. 在錯的資料夾執行 uv add

uv 依 pyproject.toml 判斷專案位置，在專案外執行會裝錯地方。先 cd 進專案資料夾再操作。

總結

虛擬環境讓每個專案的套件互不干擾；uv 流程只要四個指令：uv init 建專案、uv add 裝套件、uv run 執行、uv sync 還原。記住鐵則：用 uv 的專案就全程用 uv run 執行。下一篇學例外處理，讓程式遇到錯誤不再直接當掉。

延伸閱讀

ㄚ槌