uv 是 Astral 公司推出的一款基於 Rust 編寫的「 Python 套件管理工具 」，雖然 Python 套件管理生態存在多種工具如 pip 、 poetry 、 conda 等，但在效能、相容性和功能上 uv 都有出色表現。得益於使用 Rust 進行編寫，uv 工具的速度讓人驚艷 ；且從

  • 安裝管理 Python 版本
  • 虛擬環境使用
  • 掌控 package
  • 專案依賴

以上 uv 全部都統整好了，其目標是取代多種現有工具，為 Python 專案的開發和管理帶來了新的選擇。 uv 也成為 Astral 公司繼 Ruff(Python 程式碼檢查器和格式化工具) 之後，另一個知名的產品。

一直以來 python 開發管理環境的的各式工具，都多到讓人頭疼，多種工具分散使用如：

  • 下載 python 最新版本，有人去官網，有人用 homebrew、apt、yum ，或者 pyenv
  • 為了避免依賴衝突，使用 「venv」或者 「virtual env」建立虛擬環境
  • 安裝 package 工具也非常多種： pip 、 poetry …

那 uv 目前集成以上所有的功能，筆記一下使用 uv 開發的常用 CLI。

uv 管理 python 版本

uv 可以安裝和管理不同的 Python 版本，

# 列出 uv 支援的 python 版本
uv python list

#  安裝某個 python 版本
uv python install XXXX

# 使用特定版本 python 如 3.13 執行 xxx.py ; 如果沒安裝的話會直接幫忙安裝
uv run -p 3.13 xxx.py 
# python互動介面
uv run -p 3.13 python

# 使用系統 python 或目前工程的虛擬環境執行 xxx.py
uv run xxx.py

使用 uv 來管理 Python 專案

# 當前目錄創建 uv 工程 ，並使用 python 3.13
uv init -p 3.13

uv init <project dir>

透過 init 建立專案之後，會自動將專案使用 Git 來管理，且 uv 工具會產生了一些預設檔，而 uv 主要是有兩個 file：

  • pyproject.toml ：定義專案的主要依賴，包括專案名稱、版本、描述、支援的 Python 版本等信息
  • uv.lock ：記錄項目的所有依賴，包括依賴的依賴，且跨平台，確保在不同環境下安裝的一致性

    uv.lock 這個檔案就是專案依賴關係的完整快照，它能確保專案在不同機器上的運作環境保持一致，詳細記錄了每個套件以及它依賴的套件的情況，由 uv 自動管理，不要手動編輯

# 同步專案依賴
# 同步會自動尋找或下載適當的 Python 版本
#   建立並設定專案的虛擬環境
#   建立完整的依賴清單並寫入 uv.lock 文件
#   最後將依賴同步到虛擬環境
uv sync

# 新增依賴 ; 若沒有虛擬環境，這時 uv 也會順便幫忙創建 .venv
uv add XXX

# 刪除依賴 
uv remove XXX

# 列印依賴樹
uv tree

# 既然使用 uv 管理專案的話，就使用 uv 的命令來運行程式碼，不要像以前那樣使用 python xxx.py 來運行
uv run XXX.py

uv tool

uv tool 會在一個臨時的、隔離的環境中安裝和執行 Python 工具。 例如想用 Ruff 工具來檢查一下 code 是否符合規範，但是我們現在的環境中並沒有安裝 Ruff。解決這個問題最直接的是把想用的工具當作依賴引入進來 :

uv add ruff --dev

在這裡特別加上一個 --dev 是避免在打包的時候把 Ruff 也一起打包進來，但其實使用了 --dev 也不太合適，因為它本身是一個工具和 code 是不相關的，適合使用 --dev 的範例比如說:

  • 單元測試用到的 pytest
  • mock lib 等等

故比較推薦使用 uv tool install ruff，這時候 Ruff 就是脫離目前的專案獨立運作的，可以使用 which 來查看到它的路徑並不是當前的虛擬環境

用 uv tool install 安裝的工具是整個系統都可用的，而且 uv 在安裝工具的時候會為每個工具建立自己的虛擬環境，所以我們也不需要擔心庫之間的衝突

uv tool list

uv 配合 poetry 管理的專案

# uv 管理 poetry
uv tool install poetry

# 使用 uv 管理的 poetry 來安裝專案依賴
uv tool run poetry install


# 選定 python 版本
uv python pin 3.11

# 目錄下生成虛擬環境
uv venv

參考資料