uv 运行 Python 脚本需显式使用 uv run python script.py，它自动解析 pyproject.toml 或 requirements.txt 并在隔离环境执行；直接 python script.py 不触发依赖解析，易报 ModuleNotFoundError。

uv 可以直接运行 Python 脚本，但默认不加载项目依赖 —— 你得显式激活虚拟环境或用 uv run 命令，否则会报 ModuleNotFoundError。

uv run 是执行项目脚本的正确入口

直接调用 python script.py 不走 uv 的依赖解析逻辑；uv run 会自动读取 pyproject.toml 或 requirements.txt，在隔离环境中执行脚本，等价于先 uv venv + 激活 + python。

• 确保项目根目录下有 pyproject.toml（哪怕只有 [build-system]）或 requirements.txt
• 运行命令：uv run python script.py（注意不是 uv run script.py）
• 支持传递参数：uv run python main.py --verbose --port 8000
• 若脚本带 shebang（如 #!/usr/bin/env python），仍需显式写 python script.py，uv 不解析 shebang

uv venv + uv pip sync 后手动激活，适合调试和多脚本场景

当你要反复运行多个脚本、或需要交互式调试（如 uv run python -i 不够用）时，建一个专用虚拟环境更可控。

Python uv 0.12.20

Python uv 0.12.20 是 Astral 开发的 Python 包与项目管理工具，支持依赖解析、虚拟环境、Python 版本及项目锁文件管理。本下载包适用于 Windows x64，解压后可使用 uv 命令。

下载

• 创建环境：uv venv .venv（路径可自定义）
• 同步依赖：uv pip sync requirements.txt（或 pyproject.toml 中的 [project.dependencies]）
• 激活后执行：source .venv/bin/activate && python tools/migrate.py（Linux/macOS）
• Windows 用户用：.venv\Scripts\activate.bat && python tools/migrate.py
• 注意：uv venv 默认不安装 setuptools 和 wheel，如脚本依赖构建逻辑，加 --seed

常见错误：ModuleNotFoundError 却误以为是 uv 安装问题

这个错几乎全是路径或作用域问题，和 uv 本身是否装对无关。

立即学习“Python免费学习笔记（深入）”；

• 脚本里用了相对导入（from .utils import helper），但没用 -m 方式运行 → 改成 uv run python -m mypackage.script
• pyproject.toml 里 [project] 缺失或 dependencies 为空 → uv 找不到要装啥，uv run 就只用干净 stdlib
• 脚本路径不在当前工作目录下（比如在子目录），而 uv 默认只从当前目录找配置 → 进入脚本所在目录再运行，或用 --cwd 指定（uv run --cwd ./src python app.py）
• 误把 uv pip install 当作“全局安装” → uv 的 pip 只作用于当前 venv 或默认缓存，不污染系统 Python

uv 的核心优势是快和确定性，但它不会自动猜你想用哪个环境、哪组依赖。所有“隐式行为”都得靠 pyproject.toml 显式声明，或者靠 uv run 的上下文感知能力 —— 少一个配置项，就少一层保障。