uv - Python package and project manager
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 XXXX7
# 列出目前已安裝的 Python 路徑
uv python dir
# 使用特定版本 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
# 選定 python 版本,指定創建專案的目錄
uv python pin 3.11
uv init <PROJECT_DIR>
uv init <PROJECT_DIR> --python 3.13
透過 init 建立專案之後,會自動將專案使用 Git 來管理,且 uv 工具會產生了一些預設檔,而 uv 主要是有兩個 file:
- pyproject.toml :定義專案的主要依賴,包括專案名稱、版本、支援的 Python 版本等訊息
- uv.lock :記錄項目的所有依賴,包括依賴的依賴,且跨平台,確保在不同環境下安裝的一致性
uv.lock這個檔案就是專案依賴關係的完整快照,它能確保專案在不同機器上的運作環境保持一致,詳細記錄了每個套件以及它依賴的套件的情況,由 uv 自動管理,不要手動編輯
其他還有:
- .python-version : 這個專案使用的 Python 版本,如果在 uv init 的時候沒有指定 Python 版本,那麼就會用已安裝的最高版本。
# 同步專案依賴
# 同步會自動尋找或下載適當的 Python 版本
# 建立並設定專案的虛擬環境
# 建立完整的依賴清單並寫入 uv.lock 文件
# 最後將依賴同步到虛擬環境
uv sync
# 新增依賴 ; 若沒有虛擬環境,這時 uv 也會順便幫忙創建 .venv
# 會修改 pyproject.toml 與 uv.lock
uv add XXX
# 刪除依賴
uv remove XXX
# 列印依賴樹
uv tree
# 有使用 uv 管理專案的話,可以用 uv 的命令來運行程式碼,不要像以前那樣使用 python xxx.py 來運行
uv run XXX.py
# 指定 Python 3.11 版本來執行
uv run --python 3.11 XXX.py
# 目錄下生成虛擬環境
uv venv
# 管理臨時的虛擬環境
uv cache dir
uv cache clean
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 在安裝工具的時候會為每個工具建立自己的虛擬環境,所以不需要擔心 lib 之間的衝突
uv tool list
uv tool install <PACKAGE NAME>
uv tool upgrade <PACKAGE NAME>
uv tool uninstall <PACKAGE NAME>
### 以下範例使用 uv 配合 poetry 管理的專案 ###
# uv 管理 poetry
uv tool install poetry
# 使用 uv 管理的 poetry 來安裝專案依賴
uv tool run poetry install

