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