当终端不在项目目录时，uv run /path/to/script.py 会因无法定位项目配置和依赖而失败；可通过 --project 指定项目根目录，或显式激活项目虚拟环境来解决。
当终端不在项目目录时，`uv run /path/to/script.py` 会因无法定位项目配置和依赖而失败；可通过 `--project` 指定项目根目录，或显式激活项目虚拟环境来解决。
uv run 的核心设计是基于当前项目上下文（即 pyproject.toml、uv.toml 和 .venv 所在目录）解析依赖并执行脚本。因此，当你在其他路径下调用 uv run /full/path/to/script.py 时，uv 会尝试从当前工作目录向上查找项目配置，而非从脚本路径推断项目位置——这导致依赖解析失败。
✅ 推荐方案：使用 --project 显式指定项目根目录
这是最符合 uv 哲学、安全且可复现的方式。只需将项目根目录（含 pyproject.toml）传给 --project 参数：
uv run --project /path/to/your/project my_script.py
⚠️ 注意：
- 脚本路径（如
my_script.py）是相对于项目根目录的相对路径，不是绝对路径； - 若脚本位于子目录，写成
src/my_script.py即可； - 绝对路径不被支持（如
--project /proj my_script.py✅，但--project /proj /proj/src/my_script.py❌）。
✅ 正确示例（假设项目结构为 /home/user/myapp/pyproject.toml，脚本为 /home/user/myapp/scripts/main.py）：
inference.sh 的 Python SDK：运行 AI 应用、构建智能体，并集成 150 多个模型。包名：inferencesh (pip install inferencesh)。支持同步/异步……
# 在任意目录下执行 uv run --project /home/user/myapp scripts/main.py
⚙️ 备选方案：手动激活项目虚拟环境
若需更高灵活性（例如调试或集成到非 uv 流程中），可直接调用项目 .venv 中的 Python 解释器：
# 激活（Linux/macOS） source /path/to/your/project/.venv/bin/activate python scripts/main.py # 或跳过激活，直接调用（推荐，避免污染 shell 环境） /path/to/your/project/.venv/bin/python scripts/main.py
? 提示：.venv 路径默认在项目根目录下，也可通过 uv python list --known 或检查 uv.toml 中 [virtualenvs] 配置确认实际位置。
? 总结
| 方式 | 适用场景 | 是否推荐 | 关键注意事项 |
|---|---|---|---|
uv run --project <root><rel_path></rel_path></root> |
标准化、可复现的脚本执行 | ✅ 强烈推荐 | 脚本路径必须为相对路径；确保 <root></root> 下存在 pyproject.toml
|
直接调用 .venv/bin/python
|
CI/CD、跨工具链集成、快速验证 | ✅ 实用备选 | 需确保虚拟环境已创建（可先运行 uv sync） |
无论采用哪种方式，请始终优先保证项目已通过 uv sync 同步依赖——uv run 不会自动安装缺失依赖（除非启用 --upgrade），而显式调用 Python 时更依赖环境完整性。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
