如何在 Windows 上安裝及使用 uv 套件管理工具?
uv 是一個同時管理 Python 版本與專案環境的工具,在 Mac 和 Windows 上使用相同的指令。 本文會用官方指令在 Windows 上安裝 uv,然後驗證它能正常運作。
為甚麼用 uv
uv 取代了好幾個你原本要逐一安裝的工具,而且速度快得多。詳情請參閱我的 〈使用 uv 設定 VS Code + Python 指南〉。本文適用於 Windows; Mac 用戶請參閱本文的 Mac 版本。
觀看示範影片
在 Google Drive 觀看影片 1 · 在 Google Drive 觀看影片 2 (無需帳戶)。
安裝指令
開啟 PowerShell(如影片所示,或按 Win + X),貼上以下指令,
再按 Enter:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
三個部分很重要:
irm是Invoke-RestMethod的縮寫——它會下載安裝腳本。iex是Invoke-Expression的縮寫——它會執行該腳本。-ExecutionPolicy ByPass讓這一條指令可以執行下載的腳本,即使你的電腦平時會封鎖它們。它只對這條指令生效,不會改變系統層面的原則。
這個腳本是 uv 的開發公司 Astral 發佈的官方腳本。最新說明請見 docs.astral.sh/uv/getting-started/installation。
驗證安裝
關閉 PowerShell 視窗並重新開啟一個——這一步很重要,因為安裝程式會把
uv 加入你的 PATH,而已開啟的視窗看不到這個變更。
請在英文輸入法狀態下輸入下面指令中的兩個連字號。如果中文輸入法正在使用中,兩個連字號 可能會變成不同的字元,導致指令無法執行。
uv --version
預期輸出大致如下(你的版本號可能不同):
uv 0.13.6
看到版本號就代表完成了。
Windows 疑難排解
如果開啟新視窗後 uv --version 仍顯示「is not recognized」,請參閱我的
〈VS Code + Python 設定指南〉中的
Windows 疑難排解部分。裡面有逐步的修正方法,包括其他安裝 uv 的方式。
在存放你自己程式的資料夾中使用 uv
步驟 1:在 VS Code 中開啟資料夾
選擇 File → Open Folder,選取存放 main.py 和
requirements.txt 的資料夾。然後選擇
Terminal → New Terminal 開啟終端機,並確認它顯示的是
PowerShell。
步驟 2:為此資料夾選擇 Python 版本
依次執行以下兩個指令:
uv python install 3.12.10
uv python pin 3.12.10
- 第一個指令會把 Python 3.12.10 下載到你的電腦。這只需做一次,其他專案之後可以重複使用這個 Python 版本。
- 第二個指令告訴這個資料夾使用 Python 3.12.10,並把這個選擇儲存在名為
.python-version的小檔案中。之後任何人——或任何程式——開啟這個資料夾,都會使用同一個版本。
步驟 3:安裝程式所需的套件——從兩個選項中擇一
選項 1
uv init
uv add -r requirements.txt
uv init 會建立一個 Python 專案檔案 pyproject.toml。TOML 是
Tom's Obvious Minimal Language 的縮寫——一種為人類而設的設定檔格式
(toml.io)。這個檔案記錄了
專案所需的 Python 版本和套件。
uv add -r requirements.txt 會讀取套件清單,把每個套件安裝到專案的環境中。
選項 2
uv sync
uv sync 會嚴格按照資料夾中 uv.lock 檔案所列的套件進行安裝,
並移除多餘的套件,讓你得到與原專案相同的環境。因此它適合你從別人那裡下載的資料夾,
例如 GitHub 專案。在選項 2 中,請勿執行 uv init:資料夾中已有
pyproject.toml,uv 不會取代它。
步驟 4:執行程式
uv run main.py
要執行程式時,輸入 uv run,後面加上程式的檔案名稱,例如
main.py。
每個資料夾只需做一次步驟 1 至 3。之後再次開啟資料夾時,直接執行程式即可。
如果套件沒有變動,你只想修改程式,編輯 main.py 後再次輸入
uv run main.py 即可。
我認為一個好習慣是把所有套件都記錄在 requirements.txt 中。新增套件時,
先編輯 requirements.txt 加入套件並儲存,然後再次輸入
uv add -r requirements.txt。無論你在步驟 3 選擇了選項 1 還是選項 2,
這個習慣都適用:uv add -r requirements.txt 會更新專案記錄並安裝新增的
套件,讓一切保持同步。
步驟 5:把 VS Code 指向這個環境
按 Ctrl + Shift + P 開啟命令面板,輸入
Python: Select Interpreter,然後選取 uv 為此資料夾建立的環境。
它的標籤類似 Python 3.12.10 ('.venv': venv),路徑以資料夾內的
.venv\Scripts\python.exe 結尾——例如
C:\...\folder-ai-hello-world\.venv\Scripts\python.exe。上方第二段影片
有示範這一步。選取後,你還有第二種執行程式的方式:在編輯器中開啟檔案,點擊
Visual Studio Code 右上角的播放(三角形)按鈕。