uv Package Manager Note

安裝多個 Python 版本 (How to install multiple python versions)

uv 可以輕鬆管理和安裝多個 Python 版本，無需依賴其他工具（如 pyenv）。

安裝特定版本

uv python install 3.12

安裝多個版本

uv python install 3.10 3.11 3.12

列出已安裝的版本

uv python list

使用特定版本執行

uv 會自動偵測專案所需的 Python 版本（透過 .python-version 或 pyproject.toml），也可以手動指定：

  uv run --python 3.11 main.py

初始化專案 (How to init the project)

使用 uv init 指令可以快速建立一個新的 Python 專案結構。

基本初始化

uv init

這會建立以下檔案：

• pyproject.toml: 專案設定檔。
  • .python-version: 指定專案使用的 Python 版本。
  • hello.py: 範例程式碼（預設為應用程式專案）。
  • README.md: 專案說明文件。
  • .gitignore: Git 忽略檔案設定。

初始化為函式庫 (Library)

如果你要開發的是一個可被引用的套件（Library），可以使用 --lib 參數：

uv init --lib

這會建立 src/ 目錄結構。

pyproject.toml 與 Lock File

pyproject.toml

這是現代 Python 專案的標準設定檔 (PEP 518/621)。它定義了：

• 專案元數據 (Metadata)：如專案名稱、版本、作者、描述等。
• 依賴列表 (Dependencies)：專案執行所需的套件及其版本限制。
• 構建系統 (Build System)：定義如何打包專案。
• 工具設定：其他工具（如 Ruff, Pytest）的設定也可以放在這裡。

uv.lock (Lock File)

當你使用 uv 安裝或新增套件時，會自動產生此檔案。它記錄了所有依賴套件（包含直接依賴和傳遞依賴）的確切版本和雜湊值 (Hash)。

• 用途：確保在不同環境（開發、測試、生產）中安裝的套件版本完全一致 (Reproducible Builds)。
• 注意：不應手動編輯此檔案，應透過 uv 指令來更新。

新增套件與虛擬環境 (How to add a package)

使用 uv add 指令來新增套件。

新增套件

uv add requests

新增開發依賴 (Dev Dependencies)

uv add pytest --dev

新增套件後會發生什麼事？

當你執行 uv add <package> 時，uv 會執行以下動作：

1. 建立虛擬環境 (Virtual Environment)： 如果專案目錄下還沒有虛擬環境，uv 會自動建立一個 .venv 資料夾。這確保了專案依賴與系統 Python 環境隔離。
2. 安裝套件： 將指定的套件及其依賴安裝到 .venv 中。
3. 更新 pyproject.toml： 將套件名稱和版本限制寫入 pyproject.toml 的 dependencies 區塊。
4. 更新 uv.lock： 解析所有依賴關係，並將確切的安裝版本鎖定在 uv.lock 檔案中。

手動建立虛擬環境

通常 uv add 或 uv run 會自動處理虛擬環境的建立。如果你需要手動建立，可以使用：

uv venv

這會在當前目錄下建立 .venv。啟用方式與標準 venv 相同：

• macOS/Linux: source .venv/bin/activate
• Windows: .venv\Scripts\activate