全部速查表Python 開發

uv

uv 0.4+

uv CLI 命令快速參考：Python 專案初始化、依賴管理、虛擬環境、lockfile 解析、tool runner、自我更新——附常用參數與實作範例。

39 條命令

安裝 uv

curl -LsSf https://astral.sh/uv/install.sh | sh

macOS／Linux 官方一行安裝指令——把 uv 安裝到 `~/.local/bin`，並把 PATH 加入當前 shell。

curl -LsSf https://astral.sh/uv/install.sh | sh

pipx install uv

透過 pipx 將 uv 安裝為隔離的 CLI 工具（推薦用於受管制的 Python 安裝）。

pipx install uv

winget install --id=astral-sh.uv

透過 Windows Package Manager 安裝 uv（Windows 10／11）。

winget install --id=astral-sh.uv

自我更新

uv self update

把 uv 更新到最新發行版。使用 `--preview` 可取得下一個預發行版。

--preview；--stable

uv self update

Python 版本

uv python install <ver>

下載 Python 直譯器到 uv 的受管快取（`~/.cache/uv`／`%LOCALAPPDATA%\uv`）。可傳 `3.12`、`3.11.9`，甚至 nightly 的 `cpython-3.13.0a5`。

3.12；3.11.9；[email protected]；--mirror

uv python install 3.12

uv python list

列出 uv 可下載的所有 Python 直譯器（CPython、PyPy、free-threaded build）。使用 `--only-installed` 只篩選已下載的。

--only-installed；--all-versions；--arch；--os

uv python list --only-installed

uv python find

印出 uv 在當前目錄會使用的直譯器路徑。會參考 `.python-version`、`pyproject.toml` 與當前虛擬環境。

uv python find 3.12

uv python pin <ver>

為當前專案鎖定 Python 版本——寫入 `.python-version`。CI／Docker 可讀此檔以對齊本地直譯器。

uv python pin 3.12

專案初始化

uv init <name>

搭建新 Python 專案：`pyproject.toml`、hello-world 模組、`.gitignore`、可選的測試／README。

--package 建立為可發佈套件；--lib 建立為函式庫；--bare 不產生 source layout；--python <ver>；--no-readme；--no-pin-python

uv init my-app --package --python 3.12

uv init --lib <name>

初始化函式庫專案（src layout，可 `from <name> import ...`）。

uv init my-lib --lib

同步

uv sync

把 `pyproject.toml` 與 `uv.lock` 中宣告的所有依賴安裝到專案虛擬環境。具等冪性；`--frozen` 跳過 lockfile 更新，`--locked` 若需變動則失敗。

--frozen；--locked；--no-dev；--extra <name>；--all-extras；--group <name>；--no-install-project

uv sync --all-extras

uv lock

解析並寫入 `uv.lock` 而不安裝。使用 `--check` 驗證它與 `pyproject.toml` 一致（CI 中很方便）。

--check；--upgrade；--upgrade-package <pkg>；--frozen；--dry-run

uv lock --check

新增／移除

uv add <pkg>

把依賴加入 `pyproject.toml`、更新 `uv.lock`，並安裝到虛擬環境。

--dev；--group <name>；--optional <extra>；--upgrade；--<specifier>；--editable <path>；--raw；--no-sync；--python <ver>

uv add requests rich

uv add 'requests>=2.32'

以版本指定符（PEP 440）加入依賴。建議加上引號以避免 shell 解析問題。

uv add 'requests>=2.32,<3'

uv add --dev pytest ruff mypy

加入僅供開發使用的依賴——會寫入 `pyproject.toml` 的 `[dependency-groups].dev`。

uv add --dev pytest ruff

uv add --group docs sphinx

加入具名依賴群組。可用 `uv sync --group docs --group lint` 同時安裝多個群組。

uv add --group lint ruff mypy

uv remove <pkg>

從 `pyproject.toml`、lockfile 與虛擬環境中移除依賴。

--dev；--group <name>；--optional <extra>

uv remove requests

執行

uv run <cmd>

在專案虛擬環境內執行指令。若虛擬環境不存在會自動建立。

--with <pkg> 加入臨時依賴；--with-requirements <file>；--no-sync；--locked；--frozen；--isolated；--refresh-package <pkg>；--package <name>

uv run python -m myapp

uv run pytest

執行專案虛擬環境中安裝的工具——不需要先啟用虛擬環境。

uv run pytest -x --cov

uv run --with requests python -c 'print(requests.__version__)'

執行帶有一次性依賴的臨時指令稿，之後會被快取供下次使用。

uv run --with httpx python -c 'import httpx; print(httpx.get("https://example.com").status_code)'

uv run script.py

執行使用 PEP 723 inline metadata 的 Python 指令稿（uv 會讀取檔頭的 `# /// script` 區塊並即時解析）。

--no-sync

uv run ./hello.py

管理虛擬環境

uv venv

在 `.venv` 建立專案虛擬環境。使用 `--seed` 可一併安裝 pip + setuptools。

<path>；--python <ver>；--seed；--no-seed；--prompt <name>；--system-site-packages；--clear；--relocatable

uv venv --python 3.12

uv venv --seed

建立虛擬環境並一併安裝 pip／setuptools／wheel——虛擬環境內需要 `pip install` 工作流時必要。

uv venv --seed --python 3.11

uv remove

刪除專案虛擬環境與 lockfile。與 `uv sync` 搭配可重新開始。

uv remove && uv sync

執行 CLI 工具

uvx <tool>

在臨時環境中執行 CLI 工具（`uv tool run` 的別名）。首次使用後會被快取。

<tool>@<ver>；--from <pkg>；--with <dep>；--upgrade；--quiet

uvx ruff check .

uvx --from 'pycowsay>=2.0' cowsay 'Hello uv!'

執行特定套件所附的工具（套件名稱與 CLI 名稱不同時）。

uvx --from 'sqlfluff' sqlfluff lint models/

安裝工具

uv tool install <pkg>

把全域 CLI 工具安裝到隔離環境（類似 pipx）。工具會加入 PATH。

--python <ver>；--with <dep>；--reinstall；--quiet；--force

uv tool install ruff

uv tool list

列出所有透過 `uv tool install` 安裝的 CLI 工具。

uv tool list

uv tool uninstall <pkg>

解除安裝透過 `uv tool install` 安裝的 CLI 工具。

--quiet

uv tool uninstall ruff

uv tool upgrade

把所有已安裝工具升級到最新版本（會參考 `uv tool update-self` 與 pin 檔）。加上名稱可指定單一工具。

<tool>；--all；--reinstall；--quiet

uv tool upgrade --all

索引／快取

uv cache clean

清除 uv 的模組快取（`~/.cache/uv`）。搭配 `uv sync --refresh` 可強制完整重新下載。

<package>；--force

uv cache clean ruff

uv cache dir

印出 uv 用來存放已下載 wheel 的快取目錄。

uv cache dir

uv pip install <pkg>

切換到 pip 相容模式——遷移舊專案或工具仍呼叫 `pip` 時很有用。

<pkg>；-r <requirements.txt>；-e <path>；--index-url <url>

uv pip install -r requirements.txt

uv pip compile <in> -o <out>

把 `requirements.in` 解析為鎖定版本的 `requirements.txt`（類似 `pip-tools`）。

uv pip compile requirements.in -o requirements.txt --upgrade

建置／發佈

uv build

為專案建置 source distribution 與 wheel（依 `pyproject.toml` 設定使用 hatchling／setuptools／poetry core 等 plugin）。

-o <dir>；--wheel；--sdist；--no-byte-compile

uv build

uv publish

把已建置的構件上傳到 PyPI（或透過 `--index` 指定自訂索引）。

--token <pypi-token>；--index <name>；--publish-url <url>；--trusted-publishing <on|off>

uv publish --token $PYPI_TOKEN

診斷

uv --version

印出 uv 版本。

uv --version

uv help

列出所有 uv 子指令。

uv help

uv help <subcommand>

印出單一子指令的完整旗標列表。

uv help sync

商標與使用聲明

本批命令列工具速查手冊為開源社群參考資料。文中涉及的各工具的名稱、標識、商標（如 Git™、Docker™、Kubernetes®、kubectl、PostgreSQL®、MySQL®、Redis™、MongoDB®、Linux™、PowerShell™、Vim™ 等）均歸對應權利人所有，此處僅為識別與參考之目的使用。

本速查手冊的全部內容均為獨立編寫的簡化自包含參考，**與任何官方文件不存在隸屬、被認可或引用關係**。命令列表、參數說明、範例均為作者原創簡化表達；如需權威資訊，請參閱各工具的官方文件。

命令語法與參數可能在不同工具版本中有所差異。所示版本標籤對應穩定發佈版本；其他版本行為可能有所不同。本速查手冊**不代表**商標權利人的任何偏好或推薦。

如商標或版權方認為本站部分內容存在權益侵害，請發送電郵至[email protected]，我們在收到有效權屬證明後，會在合理期限內修改或移除相關內容。

本網站不對因使用本站資訊而產生的任何直接或間接損失承擔法律責任。

關於 uv

uv 是由 Astral（ruff 與 Python 型別檢查器 ty 的開發團隊）以 Rust 撰寫的極速 Python 套件與專案管理工具。於 2024 年首次發佈，uv 目標是用單一執行檔取代 pip、pip-tools、pipx、pyenv、virtualenv，以及部分 Poetry／pdm 的功能。它安裝套件比 pip 快 10–100 倍，因為它平行下載並使用全域模組快取（`~/.cache/uv`）。uv 支援標準的 `pyproject.toml`（PEP 621）以及較新的 PEP 723 inline-script metadata（單檔指令稿帶有自己宣告的依賴）。它在 macOS、Linux、Windows 上皆可運作，並以單一約 30 MB 的執行檔發佈（homebrew／pipx-installer／curl-install.sh／winget）。uv 不會把程式碼上傳到任何地方——它只與設定好的 Python 套件索引（`--index-url`，預設 PyPI）通訊。

速查頁版本 1.0.0

uv