如何在 Mac 上安裝及使用 uv 套件管理工具?
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
三個部分很重要:
curl會下載安裝腳本。-LsSf讓下載過程保持安靜,但出錯時仍會顯示錯誤訊息。- 結尾的
| 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
- 第一個指令會把 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 指向這個環境
按 Cmd + Shift + P 開啟命令面板,輸入
Python: Select Interpreter,然後選取 uv 為此資料夾建立的環境。
如果資料夾名稱是 folder-ai-hello-world,清單中會出現帶有該名稱的項目。
選取後,你還有第二種執行程式的方式:在編輯器中開啟檔案,點擊 Visual Studio Code
右上角的三角形按鈕。