如何在 Mac 上安裝及使用 uv 套件管理工具?

林邦源 · AI 筆記 · 2026年11月1日 · 閱讀時間約 5 分鐘

English 繁體中文 简体中文

uv 是一個同時管理 Python 版本與專案環境的工具,在 Mac 和 Windows 上使用相同的指令。 本文會用官方指令在 Mac 上安裝 uv,然後驗證它能正常運作。

為甚麼用 uv

uv 取代了好幾個你原本要逐一安裝的工具,而且速度快得多。詳情請參閱我的 〈使用 uv 設定 VS Code + Python 指南〉。本文適用於 Mac; Windows 用戶請參閱本文的 Windows 版本。

觀看示範影片

在 Google Drive 觀看 (無需帳戶)。

安裝指令

開啟 Terminal(按 Cmd + Space,輸入 Terminal, 然後按 Enter),貼上以下指令,再按 Enter:

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

三個部分很重要:

這個腳本是 uv 的開發公司 Astral 發佈的官方腳本。最新說明請見 docs.astral.sh/uv/getting-started/installation。

驗證安裝

關閉 Terminal 視窗並重新開啟一個——這一步很重要,因為安裝程式會在 你的 shell 設定檔中把 uv 加入 PATH,而已開啟的視窗看不到這個變更。

請在英文輸入法狀態下輸入下面指令中的兩個連字號。如果中文輸入法正在使用中,兩個連字號 可能會變成不同的字元,導致指令無法執行。

uv --version

預期輸出大致如下(你的版本號可能不同):

uv 0.13.6

看到版本號就代表完成了。

Mac 疑難排解

如果開啟新視窗後 uv --version 仍顯示 command not found, 請改用 Homebrew 安裝:brew install uv。我的 〈VS Code + Python 設定指南〉有更多關於安裝 uv 的說明。

在存放你自己程式的資料夾中使用 uv

步驟 1:在 VS Code 中開啟資料夾

選擇 File → Open Folder,選取存放 main.py 和 requirements.txt 的資料夾。然後選擇 Terminal → New Terminal 開啟終端機。

步驟 2:為此資料夾選擇 Python 版本

依次執行以下兩個指令:

uv python install 3.12.10
uv python pin 3.12.10

步驟 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 指向這個環境

按 Cmd + Shift + P 開啟命令面板,輸入 Python: Select Interpreter,然後選取 uv 為此資料夾建立的環境。 如果資料夾名稱是 folder-ai-hello-world,清單中會出現帶有該名稱的項目。 選取後,你還有第二種執行程式的方式:在編輯器中開啟檔案,點擊 Visual Studio Code 右上角的三角形按鈕。