uv 是一個極速的 Python 套件與專案管理工具，由 Astral 團隊使用 Rust 開發。它整合了套件安裝、虛擬環境管理、Python 版本管理等功能，執行速度比傳統的 pip、virtualenv 快上 10-100 倍。本文整理了日常開發中最常用的 uv 命令，依照使用情境分類，方便快速查閱。
建立專案
-
初始化當前目錄為專案
uv init
在當前目錄中建立新專案，預設會建立 .gitignore, .python-version, main.py, pyproject.toml 與 README.md 檔案。
-
在指定目錄中建立專案
uv init myproj
在 myproj 子目錄中建立新專案，目錄不存在時會自動建立。
-
建立可封裝的應用程式 (CLI、Web 等)
uv init --app myapp
使用 --app 建立應用程式專案，會在 myapp/ 目錄中建立 src/myapp/ 結構，並包含 __main__.py 作為程式進入點，適合開發命令列工具或 Web 應用程式。
-
建立可封裝的函式庫 (可被 import)
uv init --lib mylib
使用 --lib 建立函式庫專案，會在 mylib/ 目錄中建立 src/mylib/ 結構，並設定 pyproject.toml 為可發布的套件格式，適合開發可供其他專案使用的模組。
-
指定使用特定 Python 版本
uv init --python 3.12
使用 --python 參數指定專案的 Python 版本要求，會在 pyproject.toml 中設定 requires-python，並建立 .python-version 檔案。
操作腳本
-
初始化獨立腳本
uv init --script myscript.py
使用 --script 建立獨立的 Python 腳本檔案，會在檔案頂部加入特殊的內嵌依賴宣告區塊 (PEP 723)，讓腳本可以獨立管理自己的依賴套件，無需完整的專案結構。
-
初始化腳本並指定 Python 版本
uv init --script myscript.py --python 3.12
建立腳本時指定 Python 版本要求，會在腳本的依賴宣告區塊中加入 requires-python 設定。
-
在隔離環境中執行腳本
uv run myscript.py
自動偵測腳本的依賴需求並在隔離的虛擬環境中執行，若腳本包含依賴宣告會自動安裝所需套件。
-
執行腳本並臨時加載額外依賴
uv run --with click myscript.py
使用 --with 參數臨時加入額外的套件依賴，適合快速測試或執行需要額外套件的腳本，這些依賴不會寫入腳本檔案。
-
將依賴加入腳本環境 (可用 remove 移除)
uv add --script myscript.py click
將套件永久加入腳本的內嵌依賴宣告中，修改後的依賴會保存在腳本檔案內。
管理專案依賴
-
查看目前專案版本號
uv version
顯示專案目前的版本號，會讀取 pyproject.toml 中的 version 欄位。
-
新增依賴套件 (可一次指定多個)
uv add requests httpx
將套件加入專案的 pyproject.toml 並更新 uv.lock，可同時指定多個套件。套件會自動安裝到專案的虛擬環境中。
-
移除依賴套件
uv remove requests
從專案中移除指定的套件依賴，同時更新 pyproject.toml、uv.lock 及虛擬環境。
-
加入開發依賴
uv add --dev pytest ruff
使用 --dev 將套件加入為開發依賴，這些套件只在開發環境中需要，發布時不會被包含。適合測試工具、格式化工具等。
-
執行已安裝於專案的套件工具
uv run pytest
在專案虛擬環境中執行已安裝的命令列工具，會自動同步專案依賴後執行。
-
顯示依賴樹狀結構
uv tree
以樹狀圖顯示專案的依賴關係，包含直接依賴和間接依賴 (子依賴)，有助於理解套件之間的關聯性。
-
更新所有依賴到最新版本
uv lock --upgrade
更新 uv.lock 中的所有套件到符合版本限制的最新版本，不會修改 pyproject.toml 中的版本要求。
-
從 requirements.txt 批次加入依賴
uv add -r requirements.txt
從現有的 requirements.txt 檔案讀取並加入所有套件到專案中，方便從舊專案遷移。
專案建置與發布
Python 版本管理
-
列出系統中所有可用的 Python 版本
uv python list
顯示系統中所有已安裝的 Python 版本，包含 uv 管理的版本和系統原有的版本。
-
安裝指定 Python 版本
uv python install 3.13
下載並安裝指定的 Python 版本，uv 會自動管理這些版本，不會影響系統的 Python 安裝。支援精確版本號 (如 3.13.1) 或主要版本號 (如 3.13)。
-
移除已安裝的 Python 版本
uv python uninstall 3.13
移除 uv 管理的特定 Python 版本，不會影響系統安裝的 Python。
-
升級 uv 管理的 Python 版本
uv python upgrade
將所有 uv 管理的 Python 版本升級到各自系列的最新版本。
-
鎖定專案使用的 Python 版本
uv python pin 3.12
在專案目錄建立 .python-version 檔案，鎖定專案使用的 Python 版本。之後在該專案執行 uv run 等命令時會自動使用指定版本。
-
執行對應 Python (自動偵測專案版本)
uv run python
執行 Python 直譯器，會自動使用專案指定的 Python 版本 (透過 .python-version 或 pyproject.toml)。
-
強制使用指定 Python 版本執行
uv run --python 3.12 python
使用 --python 參數臨時指定要使用的 Python 版本，會覆蓋專案設定。
工具管理
-
全域安裝工具
uv tool install ruff
全域安裝 Python 命令列工具，安裝後可在任何地方直接執行。工具會安裝在獨立的環境中，避免依賴衝突。
-
安裝工具並包含額外依賴
uv tool install ipython --with matplotlib
使用 --with 在安裝工具時同時安裝額外的套件依賴，這些依賴會包含在工具的獨立環境中。
-
以可編輯模式安裝目前專案
uv tool install -e .
將當前專案以可編輯模式 (editable mode) 安裝為全域工具，修改原始碼會立即反映到已安裝的工具中，適合開發階段測試。
-
更新單一工具
uv tool upgrade ruff
將指定的工具升級到最新版本。
-
更新所有已安裝工具
uv tool upgrade --all
一次性升級所有全域安裝的工具到最新版本。
-
列出已安裝的工具
uv tool list
顯示所有透過 uv tool install 安裝的工具及其版本資訊。
-
移除工具
uv tool uninstall ruff
移除全域安裝的工具及其獨立環境。
快速執行工具 (uvx)
uvx 是 uv tool run 的簡寫別名，可以直接執行工具而不需要預先安裝，執行完畢後不會留下任何檔案。
-
快速執行 Ruff 程式碼檢查
uvx ruff check .
臨時安裝並執行 Ruff 進行程式碼檢查，執行完畢後自動清理。適合快速測試工具或在 CI/CD 中使用。
-
執行 Ruff 程式碼格式化
uvx ruff format .
使用 Ruff 格式化當前目錄的程式碼，無需預先安裝。
-
執行 pytest 測試
uvx pytest
臨時執行 pytest 測試框架，適合快速測試或在沒有安裝 pytest 的環境中執行測試。
-
執行 Black 格式化工具
uvx black .
使用 Black 格式化工具處理程式碼，無需全域安裝。
-
執行 mypy 型別檢查
uvx mypy src/
對 src/ 目錄執行 mypy 型別檢查，臨時安裝後執行。
-
使用 httpie 測試 API
uvx httpie GET https://api.github.com
快速使用 httpie 工具進行 API 測試，適合臨時需要的場景。
-
執行特定套件中的工具
uvx --from textual textual-demo
使用 --from 指定套件來源，執行該套件提供的命令。這裡執行 textual 套件中的 demo 範例。
-
執行 Jupyter Notebook
uvx --from jupyter-core jupyter notebook
臨時啟動 Jupyter Notebook，無需預先安裝整個 Jupyter 環境。
-
使用 cookiecutter 建立專案範本
uvx cookiecutter gh:audreyr/cookiecutter-pypackage
使用 cookiecutter 從 GitHub 範本快速建立專案架構，執行後即清理。
-
快速啟動 HTTP 伺服器
uvx --from http.server http.server 8000
啟動 Python 內建的 HTTP 伺服器，在 port 8000 提供當前目錄的檔案服務。
傳統工作流程支援
如果你習慣使用傳統的 Python 工作流程，uv 也完全支援：
-
建立虛擬環境
uv venv
在 .venv 目錄建立虛擬環境，行為類似 python -m venv，但速度更快。
-
建立虛擬環境並指定路徑與 Python 版本
uv venv path/to/.venv --python 3.12
在指定路徑建立虛擬環境，並使用特定的 Python 版本。
-
使用 uv 的速度執行 pip 安裝
uv pip install requests
使用 uv pip 提供與 pip 相容的介面，但執行速度遠快於傳統 pip。需要在啟用虛擬環境後使用，或搭配 --system 參數。
-
列出已安裝套件
uv pip list
列出當前環境中所有已安裝的套件，相容於 pip list 命令。
-
匯出依賴清單
uv pip freeze > requirements.txt
將當前環境的套件清單匯出為 requirements.txt 格式，包含精確的版本號。
其他相關命令
-
顯示命令說明
uv help
顯示 uv 命令的總體說明文件，包含所有可用的子命令與參數。
-
顯示子命令說明
以查詢 run 子命令用法為例：
uv help run
顯示特定子命令的詳細說明文件，比 --help 提供更完整的資訊。
💡 Windows 用戶建立透過 Chocolatey 額外安裝 less 工具，以免顯示說明分頁時發生異常。
choco install less
-
查看 uv 版本
uv self version
顯示目前安裝的 uv 版本號。
-
更新 uv 到最新版本
uv self update
將 uv 本身升級到最新發布版本，無需手動下載或重新安裝。
連結