2026年11月15日 星期日

macOS 學習筆記 : 安裝全能型 Python 工具鏈管理器 uv

uv 是一套專為 Python 生態系設計的新一代 Python 管理工具, 它是為了徹底解決 Python 長年以來環境混亂與安裝緩慢的痛點而生. uv 使用 Rust 語言開發, 執行速度非常快, 它將 pip, venv, pip-tools, pyenv, poetry 這些傳統 Python 工具整合在一起, 已不只是專案與套件管理工具, 而是全能型 Python 工具鏈管理器. uv 跨平台支援 macOS, Windows, 與 Linux 系統, 可在 Intel/AMD x86_64 與 ARM64 機器上執行, 是目前最受歡迎與最被推薦的 Python 管理工具. 

注意, 安裝 uv 工具之前必須先安裝 Homebrew, 我在前一篇測試中已在 macOS 安裝好 Homebrew, 參考 :


接下來就可以用 brew install uv 指令來安裝 uv 工具, 再用 uv 來建立指定版本的 Python 專案. 關於 uv 工具用法也可以參考我之前在 Windows 下的測試 :


本系列全部測試文章索引參考 :



1. 安裝 uv 工具 : 

開啟終端機, 輸入 brew install uv 指令安裝 uv 工具 : 

tony1966@Mac ~ % brew install uv
==> Downloading Homebrew API data
✔︎ JSON API packages.arm64_sequoia.jws.json                              Downloaded   16.1MB/ 16.1MB
==> Downloading bottle manifests
✔︎ Bottle Manifest uv (0.13.8)                                           Downloaded   16.9KB/ 16.9KB
==> Fetching downloads for: uv
✔︎ Bottle uv (0.13.8)                                                    Downloaded   15.3MB/ 15.3MB
==> Pouring uv--0.13.8.arm64_sequoia.bottle.tar.gz
🍺  /opt/homebrew/Cellar/uv/0.13.8: 17 files, 34MB
==> Caveats
zsh completions have been installed to:
  /opt/homebrew/share/zsh/site-functions

安裝完成後檢查 uv 版本確認 :

tony1966@Mac ~ % uv --version
uv 0.13.8 (Homebrew 2026-11-12 aarch64-apple-darwin)


2. 用 uv 安裝 Python : 

安裝好 uv 工具後, 就可以用 uv install 指令安裝 Python, 指令格式如下 :

uv python install 版本號 

其中版本號不是必須的, 例如 : 
  • uv python install : 
    若當前目錄有專案版本要求就裝該版; 否則自動安裝最新穩定版 (目前是 3.15). 
    未指定版本號時會先讀取專案的 .python-version 或 pyproject.toml 檔, 如果目前所在的資料夾 (或上層資料夾) 裡面已經有 .python-version 檔案, 或是 pyproject.toml 裡有宣告 requires-python (例如 >=3.12), uv 就會自動下載並安裝符合該專案需求的版本. 若在一般空目錄 (無專案設定檔), 則會自動下載並安裝目前官方最新的 Python 穩定版. 
  • uv python install 3.14 :
    安裝 3.14 系列的最新小版本 (例如 3.14.10), 實務開發最推薦, 兼顧套件相容性與最新安全性修補. 主力開發首選 3.12, 這是目前生態系最成熟, 幾乎 100% 支援所有資料分析, 金融繪圖與 AI SDK 套件. 
  • uv python install 3.12.7 :
    精準安裝指定的完整版本號, 適合團隊協作或舊專案嚴格要求特定小版本時. 
  • uv python install 3.12 3.13 : 
    一次同時下載並安裝多個版本, 常用於需要在同一台 Mac mini 測試跨版本相容性時. 
建議明確指定版本 (推薦 3.14), 不要直接用不帶參數的預設最新穩定版 (目前會抓到最新版本 3.15), 因最新的 Python 主版本剛推出時, 許多資料科學, 量化分析套件例如 pandas/numpy/scipy 或 AI 相關套件尚未釋出對應的預編譯二進位檔 (wheel), 安裝時容易觸發 "現場從原始碼編譯 C/C++ 擴充套件" 而報錯或編譯耗時極久. 

Python 各版本的現況如下 : 




可見 Python 3.14 系列經過一年的生態系演進, 到 2026 年底的現在早已度過早期相容性陣痛期, 目前已是高度成熟的主力穩定維護版, 而 3.12 與 3.13 則已進入安全性維護階段. Python 3.14 具備更成熟的自由執行緒 (Free-threaded / No-GIL) 支援與更佳的執行效能, 且未來幾年都能獲得完整的錯誤修復更新 : 




可以先用 uv python list 3.14 查詢目前 uv 收錄的 Python 3.14 最新小版本, 以下是在 Macbook Air (M2) 上查詢的結果 :

tony1966@Mac ~ % uv python list 3.14
cpython-3.14.10-macos-aarch64-none    <download available>

結果顯示 cpython-3.14.10-macos-aarch64-none 是目前最新釋出的小版本, 用下列指令就會自動抓到該系列中最新的小版本 3.14.10 版來安裝, 並設為系統預設 python 指令連結的版本 : 

uv python install 3.14 --default 

tony1966@Mac ~ % uv python install 3.14 --default
warning: The `--default` option is experimental and may change without warning. Pass `--preview-features python-install-default` to disable this warning
Installed Python 3.14.10 in 1.31s
 + cpython-3.14.10-macos-aarch64-none (python, python3, python3.14)
warning: `/Users/tony1966/.local/bin` is not on your PATH. To use installed Python executables, run `export PATH="/Users/tony1966/.local/bin:$PATH"` or `uv python update-shell`.

可見已成功安裝了 Python 3.14.10, 因為加上了 --default 參數, uv 已經在 /Users/tony1966/.local/bin 資料夾裡建立好 python, python3 和 python3.14 的執行連結. 最後一行的 warning 是提醒 /Users/tony1966/.local/bin 目前還沒寫進終端機的預設搜尋路徑 (PATH) 中, 所以現在直接打 python 可能會找不到或呼叫到舊版系統 Python :

tony1966@Mac ~ % python
zsh: command not found: python
tony1966@Mac ~ % python3
Python 3.9.6 (default, Apr 30 2025, 02:07:17) 
[Clang 17.0.0 (clang-1700.0.13.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> exit()
tony1966@Mac ~ % which python3
/usr/bin/python3 

只要在終端機執行 uv 提示的內建指令 uv python update-shell 將路徑寫入 Shell 設定檔即可 :

tony1966@Mac ~ % uv python update-shell
Created configuration file: /Users/tony1966/.zshenv
Restart your shell to apply changes

關閉目前的終端機重開一個新的才會套用此設定 :

Last login: Sat Nov 14 15:49:08 on ttys000
tony1966@Mac ~ % python 
Python 3.14.10 (main, Nov 11 2026, 00:14:32) [Clang 23.1.3 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> exit()
tony1966@Mac ~ % python3
Python 3.9.6 (default, Apr 30 2025, 02:07:17) 
[Clang 17.0.0 (clang-1700.0.13.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> exit()
tony1966@Mac ~ % which python
/Users/tony1966/.local/bin/python

可見 python 指令已經連結到新安裝的 Python 3.14; 而 python3 則仍然是原本的 Python 3.9. 可以用下列指令查詢系統裡有安裝哪些版本的 Python :

tony1966@Mac ~ % uv python list --only-installed
cpython-3.14.10-macos-aarch64-none    .local/bin/python3.14 -> .local/share/uv/python/cpython-3.14-macos-aarch64-none/bin/python3.14
cpython-3.14.10-macos-aarch64-none    .local/bin/python3 -> .local/share/uv/python/cpython-3.14-macos-aarch64-none/bin/python3.14
cpython-3.14.10-macos-aarch64-none    .local/bin/python -> .local/share/uv/python/cpython-3.14-macos-aarch64-none/bin/python3.14
cpython-3.14.10-macos-aarch64-none    .local/share/uv/python/cpython-3.14-macos-aarch64-none/bin/python3.14
cpython-3.9.6-macos-aarch64-none      /usr/bin/python3

這表示此 macOS 環境非常乾淨, 目前系統裡實際只存在兩套 Python 實體 : Python 3.9.6 與 3.14.10. 

前四行顯示同一套 Python 3.14.10 的本體與三個捷徑 (Symlink), 這四行全部指向同一份剛才用 uv python install 3.14 --default 安裝的 Apple Silicon 原生 Python 3.14.10 :
  • 第 4 行 (本體存放處) :
    .local/share/uv/python/cpython-3.14-macos-aarch64-none/bin/python3.14 是 uv 下載並儲存 Python 3.14.10 執行檔與標準函式庫的真正實體資料夾. 
  • 第 1~3 行 (命令列捷徑 & 符號連結) :
    因為加了 --default 參數, uv 在使用者執行目錄 .local/bin/ 下建立了三個指向上述本體的捷徑 (-> 代表符號連結), 只要確保 .local/bin 在 PATH 環境變數中 (透過 uv python update-shell), 以後無論在終端機輸入 python, python3, 或 python3.14, 都會自動呼叫這套最新的 3.14.10 :
    • .local/bin/python3.14
    • .local/bin/python3
    • .local/bin/python
  • 第五行 : macOS 系統內建 Python 3.9.6
    cpython-3.9.6-macos-aarch64-none   /usr/bin/python3
    這是隨著先前安裝 Xcode Command Line Tools 時 Apple 附帶裝進系統目錄的基礎 Python 版本, 這版本較舊且位於受 macOS 系統完整性保護 (SIP) 鎖定的 /usr/bin/ 目錄中, 平常完全不需要去動它或刪除它, 留給 macOS 系統內部腳本使用即可.
總之, 目前的設定非常理想, 沒有安裝任何肥大的 Conda 或多餘的重複版本. 


3. Python 專案測試 : 

以下用一個建立一個暫時專案來測試系統環境變數是否已正確指向 uv 安裝的 Python 3.14.10, 以及用 uv 建立虛擬環境第三方套件下載功能是否都能正常運作. 

首先建立測試用的專案資料夾, 切換到此資料夾後用 uv init 建立專案, 安裝第三方套件 requests, 然後分別執行一個 inline 的 Python 程式與用 nano 編輯的程式檔  : 

tony1966@TonydeMac-mini ~ % mkdir -p ~/tmp_uv_test && cd ~/tmp_uv_test 
tony1966@TonydeMac-mini tmp_uv_test % uv init 
Initialized project `tmp-uv-test`

檢視專案資料夾 : 

tony1966@TonydeMac-mini tmp_uv_test % ls -ls
total 8
8 -rw-r--r--  1 tony1966  staff  292 11月 16 10:04 pyproject.toml
0 -rw-r--r--  1 tony1966  staff    0 11月 16 10:04 README.md
0 drwxr-xr-x  3 tony1966  staff   96 11月 16 10:04 src

安裝第三方套件 requests :

tony1966@TonydeMac-mini tmp_uv_test % uv add requests   
Using CPython 3.14.10
Creating virtual environment at: .venv
Resolved 6 packages in 670ms
      Built tmp-uv-test @ file:///Users/tony1966/tmp_uv_test                                                            Prepared 6 packages in 398ms
Installed 6 packages in 6ms
 + certifi==2026.10.23
 + charset-normalizer==3.5.2
 + idna==3.20
 + requests==2.34.2
 + tmp-uv-test==0.1.0 (from file:///Users/tony1966/tmp_uv_test)
 + urllib3==2.8.0

用 uv tree 檢視專案結構 :

tony1966@TonydeMac-mini tmp_uv_test % uv tree
Resolved 6 packages in 1ms
tmp-uv-test v0.1.0
└── requests v2.34.2
    ├── certifi v2026.10.23
    ├── charset-normalizer v3.5.2
    ├── idna v3.20
    └── urllib3 v2.8.0

可見已安裝 requests 與其依賴模組. 

用 uv run 執行一個 inline 的 Python 程式 :

tony1966@TonydeMac-mini tmp_uv_test % uv run python -c "import sys, requests; print('版本:', sys.version.split()[0], '| 套件路徑:', requests.__file__)"
版本: 3.14.10 | 套件路徑: /Users/tony1966/tmp_uv_test/.venv/lib/python3.14/site-packages/requests/__init__.py

接下來用 nano 編輯一個 hello.py 檔案 : 

tony1966@TonydeMac-mini tmp_uv_test % nano hello.py  

輸入如下程式碼後按 Ctrl + O 存檔再按 Ctrl + X 跳出 nano :

def main():
    print("Hello from my-project!")

if __name__ == "__main__":
    main()




用 uv run 執行此程式 : 

tony1966@TonydeMac-mini tmp_uv_test % uv run hello.py
Hello from my-project!

可見用 uv 建立的 Python 專案可正常運行, 完成後刪除此專案 : 

tony1966@TonydeMac-mini tmp_uv_test % cd ~ && rm -rf ~/tmp_uv_test 
tony1966@TonydeMac-mini ~ % 

附帶一提, macOS 內建的 /usr/bin/nano 其實是經典編輯器 pico 的別名 (Symlink), 基本操作例如方向鍵移動, Ctrl + O 存檔, Ctrl + X 離開完全一致, 但缺少新版 GNU nano 的部分進階功能 (例如語法上色, 顯示行號等). 若需要支援語法高亮與行號的完整新版 GNU nano, 可以用 Homebrew 安裝, 指令如下 :

brew install nano

沒有留言 :