UV 开发与测试常用命令大全（mac/Linux + Windows）

说明：本清单面向日常开发与测试高频场景，优先给出可直接复制的命令。 约定：<项目目录>、<包名>、<脚本.py>、<版本号> 等为占位符，请按实际替换。 uv 版本：基于 uv ≥ 0.5.x，部分命令在旧版中可能不存在。

🌟 什么是 uv

项目定位

uv 是由 Astral 公司开发的新一代 Python 包管理器和虚拟环境管理工具，旨在成为 pip、pipenv、poetry、pipx 等工具的现代化替代品。

核心优势

核心概念

1. 项目模式 vs 全局模式

   • 项目模式：在项目目录中使用，自动创建 pyproject.toml 和 uv.lock

   • 全局模式：通过 uv tool 安装全局 CLI 工具

2. 依赖类型

   • 运行时依赖：项目运行必需的依赖

   • 开发依赖：开发和测试所需的依赖（--dev）

   • 可选依赖组：按需安装的依赖组（--optional / --group）

3. 工作流程

   # 1. 创建项目
   uv init myproject
   
   # 2. 添加依赖
   uv add requests
   uv add --dev pytest
   
   # 3. 生成锁文件
   uv lock
   
   # 4. 同步环境
   uv sync
   
   # 5. 运行命令
   uv run python script.py

为什么选择 uv

• 替代 pip + venv：一站式解决依赖和环境管理

• 替代 poetry：更快的速度和更简洁的命令

• 替代 pipx：uv tool 提供更好的全局工具管理

• CI/CD 友好：--frozen 模式确保构建一致性

📋 目录导航

💡 快速跳转：按 Ctrl+F 搜索关键词，或点击目录跳转

1. 安装与版本确认

1.1 安装 uv

mac/Linux

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

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

1.2 升级 uv 自身

mac/Linux

uv self update

Windows (PowerShell)

uv self update

1.3 查看版本与帮助

mac/Linux

uv --version
uv --help

Windows (PowerShell)

uv --version
uv --help

1.4 查看子命令帮助

mac/Linux

uv add --help
uv sync --help
uv run --help

Windows (PowerShell)

uv add --help
uv sync --help
uv run --help

2. 项目初始化

2.1 新建项目（生成 pyproject.toml）

mac/Linux

uv init myapp
cd myapp

Windows (PowerShell)

uv init myapp
Set-Location myapp

2.2 在已有目录初始化

mac/Linux

cd <项目目录>
uv init

Windows (PowerShell)

Set-Location <项目目录>
uv init

2.3 创建可执行脚本（PEP 723 内联依赖）

mac/Linux

uv init --script demo.py

Windows (PowerShell)

uv init --script demo.py

2.4 指定包名初始化

mac/Linux

uv init --name my-package myapp

Windows (PowerShell)

uv init --name my-package myapp

2.5 创建库项目（而非应用）

mac/Linux

uv init --lib mylib

Windows (PowerShell)

uv init --lib mylib

3. 虚拟环境管理

3.1 创建虚拟环境（默认 .venv）

mac/Linux

uv venv

Windows (PowerShell)

uv venv

3.2 创建指定 Python 版本的虚拟环境

mac/Linux

uv venv --python 3.12
uv venv --python 3.11

Windows (PowerShell)

uv venv --python 3.12
uv venv --python 3.11

3.3 指定虚拟环境名称/路径

mac/Linux

uv venv --name myenv
uv venv /path/to/custom/.venv

Windows (PowerShell)

uv venv --name myenv
uv venv C:\path\to\custom\.venv

3.4 激活虚拟环境（手动，通常 uv run 自动处理）

mac/Linux (bash/zsh)

source .venv/bin/activate

Windows (PowerShell)

.\.venv\Scripts\Activate.ps1

Windows (CMD)

.venv\Scripts\activate.bat

3.5 停用虚拟环境

mac/Linux

deactivate

Windows (PowerShell / CMD)

deactivate

3.6 查看虚拟环境中的 Python 路径

mac/Linux

uv run python -c "import sys; print(sys.executable)"

Windows (PowerShell)

uv run python -c "import sys; print(sys.executable)"

4. 依赖管理（核心）

4.1 添加运行时依赖 【高频】

mac/Linux

uv add requests
uv add "fastapi>=0.115"
uv add "django>=4.2,<5.0"

Windows (PowerShell)

uv add requests
uv add "fastapi>=0.115"
uv add "django>=4.2,<5.0"

4.2 一次添加多个依赖 【高频】

mac/Linux

uv add requests httpx aiohttp

Windows (PowerShell)

uv add requests httpx aiohttp

4.3 添加开发依赖（--dev） 【高频】

mac/Linux

uv add --dev pytest pytest-cov ruff mypy
uv add --dev black isort pre-commit

Windows (PowerShell)

uv add --dev pytest pytest-cov ruff mypy
uv add --dev black isort pre-commit

4.4 添加可选依赖组（--optional / --group）

mac/Linux

uv add --optional docs mkdocs mkdocs-material
uv add --group test pytest-xdist pytest-timeout

Windows (PowerShell)

uv add --optional docs mkdocs mkdocs-material
uv add --group test pytest-xdist pytest-timeout

4.5 从 Git 仓库安装依赖

mac/Linux

uv add "package-name @ git+https://github.com/user/repo.git"
uv add "package-name @ git+https://github.com/user/repo.git@v1.2.3"
uv add "package-name @ git+https://github.com/user/repo.git@main"

Windows (PowerShell)

uv add "package-name @ git+https://github.com/user/repo.git"
uv add "package-name @ git+https://github.com/user/repo.git@v1.2.3"
uv add "package-name @ git+https://github.com/user/repo.git@main"

4.6 从本地路径安装

mac/Linux

uv add "/path/to/local/package"
uv add "./libs/my-local-lib"

Windows (PowerShell)

uv add "C:\path\to\local\package"
uv add ".\libs\my-local-lib"

4.7 删除依赖

mac/Linux

uv remove requests
uv remove --dev pytest
uv remove --optional docs mkdocs

Windows (PowerShell)

uv remove requests
uv remove --dev pytest
uv remove --optional docs mkdocs

4.8 升级依赖

mac/Linux

uv lock --upgrade
uv lock --upgrade-package requests
uv lock --upgrade-package fastapi

Windows (PowerShell)

uv lock --upgrade
uv lock --upgrade-package requests
uv lock --upgrade-package fastapi

4.9 添加依赖时不自动同步环境

mac/Linux

uv add requests --no-sync

Windows (PowerShell)

uv add requests --no-sync

4.10 添加含 extras 的依赖

mac/Linux

uv add "pandas[excel,performance]"
uv add "uvicorn[standard]"

Windows (PowerShell)

uv add "pandas[excel,performance]"
uv add "uvicorn[standard]"

5. 锁文件与环境同步

5.1 生成/更新锁文件 【高频】

mac/Linux

uv lock

Windows (PowerShell)

uv lock

5.2 仅检查锁文件是否最新（不修改） 【CI专用】

mac/Linux

uv lock --check

Windows (PowerShell)

uv lock --check

5.3 同步环境（按锁文件安装所有依赖） 【高频】

mac/Linux

uv sync

Windows (PowerShell)

uv sync

5.4 同步并包含开发依赖 【高频】

mac/Linux

uv sync --dev
uv sync --group dev

Windows (PowerShell)

uv sync --dev
uv sync --group dev

5.5 同步指定依赖组

mac/Linux

uv sync --group test
uv sync --group docs --group lint
uv sync --all-groups

Windows (PowerShell)

uv sync --group test
uv sync --group docs --group lint
uv sync --all-groups

5.6 仅安装生产依赖（CI / 发布场景）

mac/Linux

uv sync --no-dev
uv sync --no-dev --no-group test

Windows (PowerShell)

uv sync --no-dev
uv sync --no-dev --no-group test

5.7 冻结模式同步（不允许改动锁文件）

mac/Linux

uv sync --frozen

Windows (PowerShell)

uv sync --frozen

5.8 不更新锁文件直接同步

mac/Linux

uv sync --no-lock

Windows (PowerShell)

uv sync --no-lock

5.9 重新安装所有包（强制刷新环境）

mac/Linux

uv sync --reinstall

Windows (PowerShell)

uv sync --reinstall

5.10 同步并重新安装指定包

mac/Linux

uv sync --reinstall-package requests

Windows (PowerShell)

uv sync --reinstall-package requests

💡 实用技巧：

• uv lock && uv sync 是完整的依赖更新流程，先更新锁文件再同步环境

• uv sync --frozen 适合 CI 环境，确保依赖版本完全一致

• 多个依赖组可合并执行：uv sync --group test --group docs

6. 运行脚本与命令

6.1 运行 Python 脚本

mac/Linux

uv run python script.py

Windows (PowerShell)

uv run python script.py

6.2 运行 Python 模块

mac/Linux

uv run python -m app.main
uv run python -m http.server 8000

Windows (PowerShell)

uv run python -m app.main
uv run python -m http.server 8000

6.3 运行项目中的 CLI 工具

mac/Linux

uv run ruff check .
uv run mypy src/
uv run pre-commit run --all-files

Windows (PowerShell)

uv run ruff check .
uv run mypy src/
uv run pre-commit run --all-files

6.4 带参数运行脚本

mac/Linux

uv run python train.py --epochs 100 --batch-size 32

Windows (PowerShell)

uv run python train.py --epochs 100 --batch-size 32

6.5 运行一次性工具（uvx / uv tool run）

mac/Linux

uvx cowsay "hello uv"
uvx black --check .
uvx httpie https://api.github.com

Windows (PowerShell)

uvx cowsay "hello uv"
uvx black --check .
uvx httpie https://api.github.com

6.6 指定 Python 版本运行

mac/Linux

uv run --python 3.12 python script.py

Windows (PowerShell)

uv run --python 3.12 python script.py

6.7 运行时不创建/使用项目环境（独立运行）

mac/Linux

uv run --no-project python -c "print('hello')"

Windows (PowerShell)

uv run --no-project python -c "print('hello')"

6.8 带环境变量运行

mac/Linux

UV_LOG=debug uv run python script.py
ENV=production uv run python app.py

Windows (PowerShell)

env:ENV="production"; uv run python app.py

7. 测试场景（pytest）

7.1 跑全量测试 【高频】

mac/Linux

uv run pytest

Windows (PowerShell)

uv run pytest

7.2 跑指定目录 【高频】

mac/Linux

uv run pytest tests/
uv run pytest tests/unit/

Windows (PowerShell)

uv run pytest tests/
uv run pytest tests/unit/

7.3 跑单个文件 / 单个用例 【调试】

mac/Linux

uv run pytest tests/test_api.py
uv run pytest tests/test_api.py::test_health
uv run pytest tests/test_api.py::TestUserAPI::test_login

Windows (PowerShell)

uv run pytest tests/test_api.py
uv run pytest tests/test_api.py::test_health
uv run pytest tests/test_api.py::TestUserAPI::test_login

7.4 失败即停 / 详细输出 / 指定关键字 【调试】

mac/Linux

uv run pytest -x
uv run pytest --maxfail=3
uv run pytest -vv
uv run pytest -k "health or login"
uv run pytest -k "not slow"

Windows (PowerShell)

uv run pytest -x
uv run pytest --maxfail=3
uv run pytest -vv
uv run pytest -k "health or login"
uv run pytest -k "not slow"

7.5 覆盖率（需安装 pytest-cov）

mac/Linux

uv run pytest --cov=app --cov-report=term-missing
uv run pytest --cov=app --cov-report=html
uv run pytest --cov=app --cov-report=xml
uv run pytest --cov=app --cov-fail-under=80

Windows (PowerShell)

uv run pytest --cov=app --cov-report=term-missing
uv run pytest --cov=app --cov-report=html
uv run pytest --cov=app --cov-report=xml
uv run pytest --cov=app --cov-fail-under=80

7.6 并行测试（需安装 pytest-xdist）

mac/Linux

uv run pytest -n auto
uv run pytest -n 4

Windows (PowerShell)

uv run pytest -n auto
uv run pytest -n 4

7.7 安静模式 / 只显示失败

mac/Linux

uv run pytest -q
uv run pytest --tb=short

Windows (PowerShell)

uv run pytest -q
uv run pytest --tb=short

7.8 标记过滤

mac/Linux

uv run pytest -m "slow"
uv run pytest -m "not integration"

Windows (PowerShell)

uv run pytest -m "slow"
uv run pytest -m "not integration"

7.9 生成 JUnit XML 报告（CI 集成）

mac/Linux

uv run pytest --junitxml=test-results.xml

Windows (PowerShell)

uv run pytest --junitxml=test-results.xml

💡 实用技巧：

• 使用 -x 或 --maxfail=N 在测试失败时立即停止，节省时间

• -k 参数支持复杂表达式：uv run pytest -k "not slow and (api or model)"

• 结合 --tb=short 减少堆栈跟踪输出，使结果更清晰

• CI 环境建议使用 --junitxml 生成报告，方便集成测试平台

8. 代码质量（lint / format / type check）

8.1 Ruff 检查与修复 【高频】

mac/Linux

uv run ruff check .
uv run ruff check . --fix
uv run ruff check . --fix --unsafe-fixes
uv run ruff check . --select=E,F,I --ignore=E501

Windows (PowerShell)

uv run ruff check .
uv run ruff check . --fix
uv run ruff check . --fix --unsafe-fixes
uv run ruff check . --select=E,F,I --ignore=E501

8.2 Ruff 格式化 【高频】

mac/Linux

uv run ruff format .
uv run ruff format . --check
uv run ruff format . --diff

Windows (PowerShell)

uv run ruff format .
uv run ruff format . --check
uv run ruff format . --diff

8.3 MyPy 类型检查 【CI专用】

mac/Linux

uv run mypy .
uv run mypy src/
uv run mypy --strict .

Windows (PowerShell)

uv run mypy .
uv run mypy src/
uv run mypy --strict .

8.4 Black 格式化（可选，ruff format 可替代）

mac/Linux

uv run black .
uv run black --check .
uv run black --diff .

Windows (PowerShell)

uv run black .
uv run black --check .
uv run black --diff .

8.5 isort 导入排序（可选，ruff 内置）

mac/Linux

uv run isort .
uv run isort --check-only .

Windows (PowerShell)

uv run isort .
uv run isort --check-only .

8.6 Pre-commit 钩子运行

mac/Linux

uv run pre-commit run --all-files
uv run pre-commit run ruff --all-files

Windows (PowerShell)

uv run pre-commit run --all-files
uv run pre-commit run ruff --all-files

9. Python 版本管理

9.1 列出可用的 Python 版本

mac/Linux

uv python list
uv python list --all-versions
uv python list --only-installed

Windows (PowerShell)

uv python list
uv python list --all-versions
uv python list --only-installed

9.2 安装指定 Python 版本

mac/Linux

uv python install 3.12
uv python install 3.11 3.10
uv python install 3.13

Windows (PowerShell)

uv python install 3.12
uv python install 3.11 3.10
uv python install 3.13

9.3 卸载 Python 版本

mac/Linux

uv python uninstall 3.10

Windows (PowerShell)

uv python uninstall 3.10

9.4 查找 Python 解释器路径

mac/Linux

uv python find
uv python find 3.12

Windows (PowerShell)

uv python find
uv python find 3.12

9.5 固定项目 Python 版本要求

mac/Linux

uv python pin 3.12

Windows (PowerShell)

uv python pin 3.12

9.6 查看当前使用的 Python

mac/Linux

uv run python --version
uv python find

Windows (PowerShell)

uv run python --version
uv python find

10. 工具管理（全局 CLI）

10.1 安装 CLI 工具

mac/Linux

uv tool install ruff
uv tool install black
uv tool install httpie

Windows (PowerShell)

uv tool install ruff
uv tool install black
uv tool install httpie

10.2 安装工具时指定 Python 版本

mac/Linux

uv tool install --python 3.12 ruff

Windows (PowerShell)

uv tool install --python 3.12 ruff

10.3 列出已安装工具

mac/Linux

uv tool list

Windows (PowerShell)

uv tool list

10.4 升级工具

mac/Linux

uv tool upgrade black
uv tool upgrade --all

Windows (PowerShell)

uv tool upgrade black
uv tool upgrade --all

10.5 卸载工具

mac/Linux

uv tool uninstall black

Windows (PowerShell)

uv tool uninstall black

10.6 查看工具安装目录

mac/Linux

uv tool dir

Windows (PowerShell)

uv tool dir

10.7 运行已安装的工具（uvx 快捷方式）

mac/Linux

uvx ruff check .
uvx black --check .
uvx --python 3.12 mypy .

Windows (PowerShell)

uvx ruff check .
uvx black --check .
uvx --python 3.12 mypy .

10.8 uvx 运行带版本的工具

mac/Linux

uvx ruff@0.9.0 check .
uvx black@24.10.0 --check .

Windows (PowerShell)

uvx ruff@0.9.0 check .
uvx black@24.10.0 --check .

11. pip 兼容接口（从 pip 迁移）

11.1 安装包（pip 风格）

mac/Linux

uv pip install requests
uv pip install "fastapi>=0.115"
uv pip install requests httpx

Windows (PowerShell)

uv pip install requests
uv pip install "fastapi>=0.115"
uv pip install requests httpx

11.2 根据 requirements.txt 安装

mac/Linux

uv pip install -r requirements.txt
uv pip install --upgrade -r requirements.txt

Windows (PowerShell)

uv pip install -r requirements.txt
uv pip install --upgrade -r requirements.txt

11.3 导出当前环境依赖

mac/Linux

uv pip freeze
uv pip freeze > requirements.txt

Windows (PowerShell)

uv pip freeze
uv pip freeze | Out-File -Encoding utf8 requirements.txt

11.4 列出已安装的包

mac/Linux

uv pip list
uv pip list --outdated
uv pip list --format=json

Windows (PowerShell)

uv pip list
uv pip list --outdated
uv pip list --format=json

11.5 查看包详细信息

mac/Linux

uv pip show requests
uv pip show --files requests

Windows (PowerShell)

uv pip show requests
uv pip show --files requests

11.6 检查依赖冲突

mac/Linux

uv pip check

Windows (PowerShell)

uv pip check

11.7 卸载包（pip 风格）

mac/Linux

uv pip uninstall requests
uv pip uninstall -y requests

Windows (PowerShell)

uv pip uninstall requests
uv pip uninstall -y requests

11.8 编译 requirements（从 pyproject.toml 导出）

mac/Linux

uv pip compile pyproject.toml -o requirements.txt
uv pip compile pyproject.toml --all-extras -o requirements-dev.txt

Windows (PowerShell)

uv pip compile pyproject.toml -o requirements.txt
uv pip compile pyproject.toml --all-extras -o requirements-dev.txt

12. 依赖树与可视化

12.1 查看依赖树

mac/Linux

uv tree
uv tree --depth 2
uv tree --package requests

Windows (PowerShell)

uv tree
uv tree --depth 2
uv tree --package requests

12.2 反向依赖查询（谁依赖了某包）

mac/Linux

uv tree --invert
uv tree --invert --package urllib3

Windows (PowerShell)

uv tree --invert
uv tree --invert --package urllib3

12.3 查看所有依赖（包括传递依赖）

mac/Linux

uv tree --all

Windows (PowerShell)

uv tree --all

12.4 只显示开发依赖树

mac/Linux

uv tree --dev

Windows (PowerShell)

uv tree --dev

12.5 标记重复依赖

mac/Linux

uv tree --show-version-specifiers

Windows (PowerShell)

uv tree --show-version-specifiers

13. 构建与发布

13.1 构建源码分发包和 wheel

mac/Linux

uv build

Windows (PowerShell)

uv build

13.2 只构建 wheel

mac/Linux

uv build --wheel

Windows (PowerShell)

uv build --wheel

13.3 只构建源码分发包

mac/Linux

uv build --sdist

Windows (PowerShell)

uv build --sdist

13.4 发布到 PyPI

mac/Linux

uv publish
uv publish --token <pypi-token>
uv publish --username <user> --password <pass>

Windows (PowerShell)

uv publish
uv publish --token <pypi-token>
uv publish --username <user> --password <pass>

13.5 发布到测试 PyPI

mac/Linux

uv publish --publish-url https://test.pypi.org/legacy/

Windows (PowerShell)

uv publish --publish-url https://test.pypi.org/legacy/

14. 缓存管理

14.1 查看缓存目录

mac/Linux

uv cache dir

Windows (PowerShell)

uv cache dir

14.2 清理所有缓存

mac/Linux

uv cache clean

Windows (PowerShell)

uv cache clean

14.3 清理特定包的缓存

mac/Linux

uv cache clean requests
uv cache clean numpy pandas

Windows (PowerShell)

uv cache clean requests
uv cache clean numpy pandas

14.4 查看缓存大小

mac/Linux

uv cache prune --ci

Windows (PowerShell)

uv cache prune --ci

15. 内联脚本（PEP 723）

15.1 创建内联依赖脚本

mac/Linux

uv init --script fetch_data.py

Windows (PowerShell)

uv init --script fetch_data.py

15.2 给脚本添加内联依赖

mac/Linux

uv add --script fetch_data.py requests
uv add --script fetch_data.py "rich>=13.0"

Windows (PowerShell)

uv add --script fetch_data.py requests
uv add --script fetch_data.py "rich>=13.0"

15.3 运行内联脚本

mac/Linux

uv run fetch_data.py

Windows (PowerShell)

uv run fetch_data.py

15.4 给脚本添加开发依赖

mac/Linux

uv add --script fetch_data.py --dev pytest ruff

Windows (PowerShell)

uv add --script fetch_data.py --dev pytest ruff

15.5 锁定内联脚本依赖

mac/Linux

uv lock --script fetch_data.py

Windows (PowerShell)

uv lock --script fetch_data.py

15.6 导出内联脚本依赖

mac/Linux

uv export --script fetch_data.py -o requirements.txt

Windows (PowerShell)

uv export --script fetch_data.py -o requirements.txt

16. 导出依赖

16.1 导出为 requirements.txt

mac/Linux

uv export --format requirements-txt -o requirements.txt
uv export --no-dev --format requirements-txt -o requirements.txt
uv export --no-hashes --format requirements-txt -o requirements.txt

Windows (PowerShell)

uv export --format requirements-txt -o requirements.txt
uv export --no-dev --format requirements-txt -o requirements.txt
uv export --no-hashes --format requirements-txt -o requirements.txt

16.2 导出包含哈希的 requirements.txt

mac/Linux

uv export --format requirements-txt --no-hashes=false -o requirements-hash.txt

Windows (PowerShell)

uv export --format requirements-txt --no-hashes=false -o requirements-hash.txt

16.3 导出包含指定依赖组

mac/Linux

uv export --group test --group docs -o requirements-dev.txt
uv export --all-groups -o requirements-all.txt

Windows (PowerShell)

uv export --group test --group docs -o requirements-dev.txt
uv export --all-groups -o requirements-all.txt

17. 工作区（Monorepo / Workspaces）

17.1 创建工作区根目录

mac/Linux

uv init workspace-root
cd workspace-root

Windows (PowerShell)

uv init workspace-root
Set-Location workspace-root

17.2 添加子包到工作区

mac/Linux

uv init --lib packages/core
uv init packages/api

Windows (PowerShell)

uv init --lib packages/core
uv init packages/api

17.3 子包添加工作区成员依赖

mac/Linux

cd packages/api
uv add core

Windows (PowerShell)

Set-Location packages/api
uv add core

17.4 从根目录同步所有子包

mac/Linux

cd workspace-root
uv sync

Windows (PowerShell)

Set-Location workspace-root
uv sync

17.5 从根目录运行子包命令

mac/Linux

uv run --package api pytest
uv run --package core python -m core.main

Windows (PowerShell)

uv run --package api pytest
uv run --package core python -m core.main

18. CI/CD 常用命令模板

18.1 最小化 CI 流水线（推荐）

mac/Linux

uv sync --frozen --dev
uv run ruff check .
uv run ruff format . --check
uv run mypy .
uv run pytest -q --cov=app --cov-report=xml

Windows (PowerShell)

uv sync --frozen --dev
uv run ruff check .
uv run ruff format . --check
uv run mypy .
uv run pytest -q --cov=app --cov-report=xml

18.2 仅检查（无测试执行）

mac/Linux

uv sync --frozen
uv run ruff check .
uv run ruff format . --check
uv run mypy .

Windows (PowerShell)

uv sync --frozen
uv run ruff check .
uv run ruff format . --check
uv run mypy .

18.3 发布前检查

mac/Linux

uv lock --check
uv sync --frozen
uv run pytest
uv build

Windows (PowerShell)

uv lock --check
uv sync --frozen
uv run pytest
uv build

18.4 GitHub Actions 示例片段

- name: Install uv
  uses: astral-sh/setup-uv@v5

- name: Install dependencies
  run: uv sync --frozen --dev

- name: Lint
  run: uv run ruff check .

- name: Test
  run: uv run pytest -q --cov=app

19. 故障排查

19.1 查看环境与解释器路径

mac/Linux

uv run python -V
uv run which python
uv run python -c "import sys; print(sys.executable)"
uv run python -c "import site; print(site.getsitepackages())"

Windows (PowerShell)

uv run python -V
uv run where.exe python
uv run python -c "import sys; print(sys.executable)"
uv run python -c "import site; print(site.getsitepackages())"

19.2 调试模式运行

mac/Linux

UV_LOG=debug uv sync
UV_LOG=trace uv run pytest

Windows (PowerShell)

env:UV_LOG="trace"; uv run pytest

19.3 详细输出模式

mac/Linux

uv sync -v
uv sync -vv

Windows (PowerShell)

uv sync -v
uv sync -vv

19.4 清理后重建环境

mac/Linux

rm -rf .venv
uv sync --dev

Windows (PowerShell)

Remove-Item -Recurse -Force .venv
uv sync --dev

19.5 检查依赖冲突（重新锁定观察报错）

mac/Linux

uv lock
uv lock --check

Windows (PowerShell)

uv lock
uv lock --check

19.6 查看 uv 自身配置

mac/Linux

uv --version
uv python list --only-installed
uv cache dir

Windows (PowerShell)

uv --version
uv python list --only-installed
uv cache dir

19.7 离线模式运行

mac/Linux

uv sync --offline
uv lock --offline

Windows (PowerShell)

uv sync --offline
uv lock --offline

19.8 指定 PyPI 镜像源

mac/Linux

uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple
uv add requests --index-url https://mirrors.aliyun.com/pypi/simple/

Windows (PowerShell)

uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple
uv add requests --index-url https://mirrors.aliyun.com/pypi/simple/

19.9 添加额外索引源（公司私服）

mac/Linux

uv sync --extra-index-url https://pypi.company.com/simple
uv add private-pkg --extra-index-url https://pypi.company.com/simple

Windows (PowerShell)

uv sync --extra-index-url https://pypi.company.com/simple
uv add private-pkg --extra-index-url https://pypi.company.com/simple

19.10 指定代理

mac/Linux

HTTPS_PROXY=http://127.0.0.1:7890 uv sync
HTTP_PROXY=http://127.0.0.1:7890 uv add requests

Windows (PowerShell)

env:HTTP_PROXY="http://127.0.0.1:7890"; uv add requests

20. pyproject.toml 配置参考

20.1 基础项目配置

[project]
name = "myapp"
version = "0.1.0"
description = "My application"
requires-python = ">=3.10"
dependencies = [
    "fastapi>=0.115.0",
    "uvicorn[standard]>=0.34.0",
    "sqlalchemy>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "pytest-cov>=6.0",
    "ruff>=0.9",
    "mypy>=1.14",
]
docs = [
    "mkdocs>=1.6",
    "mkdocs-material>=9.5",
]

20.2 uv 专属配置

[tool.uv]
dev-dependencies = [
    "pytest>=8.0",
    "ruff>=0.9",
]

[tool.uv.sources]
# 从 Git 仓库获取
httpx = { git = "https://github.com/encode/httpx.git", tag = "0.28.0" }

# 从本地路径获取
my-lib = { path = "./libs/my-lib", editable = true }

20.3 Ruff 配置（pyproject.toml）

[tool.ruff]
line-length = 100
target-version = "py312"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP"]

[tool.ruff.format]
quote-style = "double"

20.4 pytest 配置（pyproject.toml）

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
addopts = "-v --tb=short"

20.5 mypy 配置（pyproject.toml）

[tool.mypy]
python_version = "3.12"
strict = true
warn_return_any = true
warn_unused_configs = true

21. 推荐日常工作流

22. 一组可直接复制的"新项目起步"命令

mac/Linux

uv init demo
cd demo
uv add fastapi uvicorn
uv add --dev pytest pytest-cov ruff mypy
uv sync --dev
uv run ruff check .
uv run pytest

Windows (PowerShell)

uv init demo
Set-Location demo
uv add fastapi uvicorn
uv add --dev pytest pytest-cov ruff mypy
uv sync --dev
uv run ruff check .
uv run pytest

23. 常用标志速查

24. 与 pip 常用命令对照速查

25. ⚡ 高频命令速查表

快速索引：按场景查找

🚀 项目初始化与环境

📦 依赖管理

🔧 开发与测试

🧹 维护与排查

🚢 CI/CD 场景

📊 标签说明

参考来源：

• uv 官方文档：https://docs.astral.sh/uv/

• uv GitHub：https://github.com/astral-sh/uv