在 Windows 上安裝 uv#

　　官方的安裝說明文件在此：Installation | uv

　　雖然官方最推薦的是直接用 PowerShell 的 irm | iex 執行，不過若是比較擔心資安問題、也可以透過 WinGet 安裝，至少有多一層 Microsoft 的認證機制、避免中間人攻擊。

1
winget install --id=astral-sh.uv -e
2
uv --version  # 顯示版本以驗證安裝成功

　　而且如果用 PowerShell irm | iex 安裝，裝好後還要再多一步驟把它安裝到的路徑 %USERPROFILE%\.local\bin 加入環境變數 PATH；而透過 WinGet 安裝會裝在 WinGet 已經設好的 PATH 路徑下、免去這一步驟。

透過 uv 安裝 Python#

1
uv python list  # 查看所有可安裝與已安裝的版本
2
uv python install  # 安裝最新的穩定版本
3
uv python install 3.13  # 安裝指定版本

1
uv python install --default --preview-features python-install-default  # 安裝最新的穩定版本、並設為全域
2
uv python install 3.13 --default --preview-features python-install-default  # 安裝指定版本、並設為全域
3
python --version  # 顯示版本以驗證

使用 uv 管理專案#

1. 初始化

   1
   uv init  # 將目前工作目錄初始化為 Python 專案
   2
   uv init "<path>"  # 將 <path> 目錄初始化為 Python 專案；若 <path> 不存在將自動建立目錄
   

   • 其實已預設自帶 --app 參數、表示初始化為 Python 專案
   • 會建立兩個檔案：
     • pyproject.toml：記錄專案資訊，大約相當於 npm 的 package.json
     • .python-version：記錄此專案使用的 Python 版本，大約相當於 nvm 的 .nvmrc
     • 這兩個檔案都不是 uv 獨有、而是許多工具都支援的格式。
   • 預設會找目前 uv 管理的 Python 版本裡最新的那一個，一方面作為此專案的最低要求 Python 版本、記入 pyptoject.toml 裡，另一方面作為此專案須使用的 Python 版本記入 .python-version
   • 預設會附帶 git init 和建立 .gitignore，如果不想、可以加參數 --vcs none
   • 預設會建立一個空的 README.md 並加入 pyptoject.toml，如果不想、可以加參數 --no-readme

2. 切換此專案的 Python 版本

   1
   uv python pin 3.13
   

   • 會將 .python-version 內容改為指定的版本
   • 如果指定的版本超出 .pyproject.toml 指定的 requires-python 範圍，會被擋下來

3. 管理依賴

   1
   uv add requests  # 加入 requests 的最新穩定版作為正式依賴
   2
   uv add requests==2.32.5  # 加入 requests 的 2.32.5 版本作為正式依賴
   3
   uv add --dev pytest  # 加入 pytest 作為開發依賴
   4
   uv add --group lint ruff  # 加入 ruff 至「lint」依賴群組
   5
   uv remove requests  # 移除 requests 依賴
   

   • 若沒有指定版本，就會去找最新穩定版本
   • 比 npm 多了 group 的功能——可以把依賴細分成正式、開發以外更多其他的群組，其他接手此專案的開發者可以選擇性批次安裝哪些群組裡的依賴
   • 會更新 pyproject.toml 與 uv.lock，並把指定 package 安裝至此專案下的 .venv（其包含了 npm 的 node_modules 的功能）
   • 「uv.lock」是 uv 專屬的檔案，大約相當於 npm 的 package-lock.json

4. 接手專案後在本地安裝依賴

   1
   uv sync  # 安裝正式與開發依賴，不含其他 group
   2
   uv sync --no-dev  # 只安裝正式依賴
   3
   uv sync --group lint  # 只安裝「lint」group 的依賴
   4
   uv sync --all-group  # 安裝所有依賴
   

5. 執行

   1
   uv run main.py
   

   • 會用專案內的 venv 執行，其中這個 venv 的 Python 版本由 .python-version 指定、包含的 package 由 pyproject.toml 與 uv.lock 指定

使用 uv 管理單一 py 檔腳本#

1. 初始化

   1
   uv init .\test.py --script  # 建立 test.py py 檔、初始化為 Python 腳本
   

   • 只會建立 test.py 單一 py 檔，開頭會有以 # /// 包裹的一段註解（如下）、是此腳本的 Python 版本與依賴資訊

     1
     # /// script
     2
     # requires-python = ">=3.14"
     3
     # dependencies = []
     4
     # ///
     

     • 這也不是 uv 專屬、而是許多工具支援的格式。

2. 管理依賴

   1
   uv add --script test.py requests  # 加入 requests 的最新穩定版作為正式依賴
   2
   uv add --script test.py requests==2.32.5  # 加入 requests 的 2.32.5 版本作為依賴
   3
   uv remove --script test.py requests  # 移除 requests 依賴
   

   • 在 script 模式下就沒有開發依賴和 group 功能了
   • 可用 uv lock --script test.py 產生 test.py.lock 檔、放在腳本旁邊，未來 uv run 此腳本時若有找到此 lock 檔就會優先依照它的定義安裝依賴

3. 指定此腳本需要的 Python 版本

   • 直接更改開頭的「requires-python」
   • 沒有 uv python pin 功能

4. 執行

   1
   uv run test.py  # 在獨立環境使用「requires-python」指定的 Python 版本和「dependencies」指定的依賴執行
   2
   uv run --python 3.13 test.py  # 指定用 Python 3.13 執行
   3
   uv run --with numpy test.py  # 加入「dependencies」未指定的 numpy 依賴執行
   

   • 每次 uv run 時會自動確保使用正確的獨立環境與依賴，就沒有 uv sync 了

安裝與使用全域工具套件#

1
uv tool install ruff  # 安裝 ruff 至全域，大約相當於 `npm add -g`、外加管理 Python 版本
2
uv tool uninstall ruff  # 從全域解除安裝 ruff
3
uvx ruff  # 一次性執行 ruff，大約相當於 `npx`、且於獨立的 Python 環境執行

後記閒聊#

　　原本只是在還沒裝過 Python 的新電腦上想安裝 Emscripten、要求得先裝 Python，於是想說聽過 uv 鼎鼎大名、藉此機會順便來學一下，沒想到就卡在這裡四小時……

　　順便記錄一下此次追查來龍去脈時用到的幾個好用指令：

1. PowerShell (Get-Command python).Source：查目前打 python 呼叫到的實際執行檔路徑
   • 不過若是 uv install --default 這種情況、找到的只會是 %USERPROFILE%\.local\bin 底下的 Python.exe，沒辦法找到此執行檔裡再指向的下一個執行檔
2. PowerShell where.exe python：查在目前的 PATH 裡，python 所有呼叫候選執行檔
   • 實際打 python 會呼叫到裡面的第一個
3. cmd dir：查看當前目錄下的所有……物件(?)，重點是也可以看出那個 link 是 junction 還是 symbolic link

　　以及這次寫文時還遇到想在 code 裡面呈現反引號（`），學到是要改用更多反引號作為包括，比如我想呈現單個反引號、前後就用各兩個反引號來包住整段文字。

參考資料#

• uv
• ChatGPT、Gemini
• uv 與 uvx 命令全攻略：Python 開發者的極速工具指南 | The Will Will Web

延伸閱讀#

• 【Python】建立 Python 環境 - Chuan’s Space：傳統的作法