本文详解为何 uv run -m pydantic_ai_examples.pydantic_model 报错“unexpected argument '-m'”，并提供从项目初始化、依赖安装到成功运行示例的完整标准化流程。
本文详解为何 uv run -m pydantic_ai_examples.pydantic_model 报错“unexpected argument '-m'”，并提供从项目初始化、依赖安装到成功运行示例的完整标准化流程。
uv run -m 命令报错“unexpected argument '-m' found”，根本原因在于：当前工作目录未被识别为 uv 项目（即缺少 pyproject.toml 或未通过 uv init 初始化）。uv 在非项目上下文中不支持 -m 标志——它仅在已配置的项目环境中才启用模块执行模式，以确保依赖解析和包导入路径正确。
✅ 正确操作流程如下：
-
初始化 uv 项目（关键第一步）
uv init example-app cd example-app
此步骤会生成标准
pyproject.toml，使 uv 能识别项目结构与依赖上下文。 -
安装带 examples 的 pydantic-ai
注意必须使用单引号包裹 extras，并确保安装的是pydantic-ai（包名含连字符，非下划线）：uv add 'pydantic-ai[examples]'
✅ 验证安装：
uv pip list | grep pydantic-ai应显示pydantic-ai及其 extras。 -
运行示例模块
现在可安全执行：uv run -m pydantic_ai_examples.pydantic_model
若提示
ModuleNotFoundError: No module named 'pydantic_ai_examples'，说明前两步未完成或路径错误——uv run -m依赖项目配置自动将src/或已安装包加入 Python path，普通python -m无法替代。
⚠️ 注意事项：
- ❌ 不要直接在任意目录运行
uv run -m ...：uv 默认按“当前是否为项目”决定命令行为，无项目时-m被视为非法参数。 - ❌ 不要混淆包名：
pydantic_ai（旧版/非官方）≠pydantic-ai（官方 PyPI 包），安装必须用后者。 - ? 示例需 OpenAI API 密钥：运行前务必设置环境变量，否则会抛出
MissingAPIKeyError：export OPENAI_API_KEY="sk-..." # 或临时运行 OPENAI_API_KEY="sk-..." uv run -m pydantic_ai_examples.pydantic_model
? 补充说明：若你仅想快速试用（无需项目管理），也可跳过 uv init，改用 uv venv 创建独立环境后手动激活并安装：
uv venv .venv && source .venv/bin/activate # Linux/macOS uv pip install 'pydantic-ai[examples]' python -m pydantic_ai_examples.pydantic_model # 此时 python -m 可用，因包已安装至当前环境
但推荐始终采用 uv init + uv add + uv run 的声明式项目工作流——它更可靠、可复现，且与现代 Python 工具链（如 ruff、mypy）天然兼容。
