uv 默认实现项目级依赖隔离,每个项目目录即独立环境,自动识别 pyproject.toml 或 uv.lock,不复用全局或其他项目环境。

uv 默认就做项目级依赖隔离,不需要手动激活环境
uv 的设计核心是「每个项目目录即一个独立环境」。它不会复用全局 Python 或其他项目的 .venv,只要你在项目根目录(含 pyproject.toml 或 uv.lock)下运行命令,uv 就自动识别并使用该项目专属的依赖快照。
常见错误现象:在项目 A 里 uv add requests==2.31.0,然后切到项目 B 目录执行 uv run python -c "import requests; print(requests.__version__)" 却报错或显示旧版本——这通常是因为你没在项目 B 目录下执行 uv sync,或者项目 B 根目录压根没有 pyproject.toml。
- 确保每个项目都有自己的
pyproject.toml(用uv init初始化最稳妥) -
uv add、uv sync、uv run等命令必须在项目根目录执行,否则 uv 会回退到“临时环境”或报错 - 不要手动
source .venv/bin/activate;uv 大多数命令不依赖 shell 激活状态
为什么 uv add 后其他项目不受影响
uv 不会修改全局 site-packages,也不动其他项目的 .venv。它只做三件事:更新当前项目的 pyproject.toml、重算依赖树、写入 uv.lock、把包装进当前项目的 .venv(如果存在)或内部缓存路径。
关键机制在于:uv add 不会卸载未被声明的间接依赖,除非该包已不被任何直接依赖引用;而 uv remove 也只移除显式声明的包及其“孤儿化”的传递依赖。
Python uv 0.12.20 是 Astral 开发的 Python 包与项目管理工具,支持依赖解析、虚拟环境、Python 版本及项目锁文件管理。本下载包适用于 Windows x64,解压后可使用 uv 命令。
- 项目 A 安装了
fastapi==0.110.0,它依赖pydantic>=2.6.0→ uv 自动选pydantic==2.8.2 - 项目 B 安装
pydantic==1.10.15(老版本),uv 会为它单独拉取并隔离存放,不覆盖项目 A 的pydantic==2.8.2 - 两个项目共用的底层 Rust 缓存(
~/.cache/uv)是只读共享的,不互相污染
跨项目 Python 版本不同,uv 怎么处理
Python 解释器版本是隔离粒度的一部分。uv 允许你在每个项目中通过 .python-version 或 pyproject.toml 的 requires-python 字段锁定解释器,再用 uv python pin 绑定本地可用版本。
错误示例:uv venv --python 3.9 在项目 A 执行后,项目 B 运行 uv run 却用了系统默认的 3.11 ——这是因为项目 B 没有指定 Python 版本约束,uv 就按当前 shell 的 python 路径走。
- 推荐做法:在项目根目录执行
uv python pin 3.9.18,会生成.python-version文件 - 同时在
pyproject.toml中补上[project] requires-python = ">=3.9,,避免别人误用不兼容版本 -
uv sync会检查当前 Python 是否满足requires-python,不满足则报错,不会强行降级解释器
PyCharm 或 VS Code 里怎么确认 uv 正确隔离了依赖
编辑器有时会缓存解释器路径或依赖列表,导致“明明装了却 import 报错”。根本原因不是 uv 失效,而是 IDE 没刷新项目环境上下文。
典型表现:在终端里 uv run python -c "import anthropic" 成功,但在 PyCharm 的 Python Console 里执行同一行却报 ModuleNotFoundError。
- PyCharm:设置解释器时选 “System Interpreter”,路径指向项目下的
.venv/Scripts/python.exe(Windows)或.venv/bin/python(macOS/Linux) - VS Code:打开命令面板(Ctrl+Shift+P),运行 “Python: Select Interpreter”,选择项目内
.venv下的 Python - 务必关闭并重启终端/IDE 内置 Terminal,因为 uv 的环境变量注入(如
PYTHONPATH)只对新进程生效
uv.lock,多人协作时就可能因解析策略微调导致依赖版本漂移。

















