检测是不是在虚拟环境中

1# macos / Linux
2echo $VIRTUAL_ENV
3which python
4# Windows
5$env:VIRTUAL_ENV
6Get-Command python

---

uv 不需要虚拟环境直接安装依赖

uv 判断环境的逻辑：

1. 当前目录是否有 pyproject.toml
2. 是否存在 .venv
3. 自动绑定该虚拟环境

所以你只要在项目目录：

1cd 项目目录
2uv add xxx

就会装到：

1./.venv/lib/pythonX/site-packages

---

uv 项目结构

1.
2├── .venv
3│   ├── bin
4│   ├── lib
5│   └── pyvenv.cfg
6├── .python-version
7├── README.md
8├── main.py
9├── pyproject.toml
10└── uv.lock

pyproject.toml 包含有关您的项目的元数据

.python-version 文件包含项目的默认 Python 版本。此文件告诉 uv 在创建项目虚拟环境时使用哪个 Python 版本

.venv 文件夹包含项目的虚拟环境，这是一个与系统其他部分隔离的 Python 环境。uv 将在这里安装项目的依赖项

uv.lock 是一个跨平台的锁文件，其中包含项目依赖项的精确信息。与用于指定项目总体需求的 pyproject.toml 不同，锁文件包含项目环境中已安装的精确解析版本。此文件应纳入版本控制，以便在不同机器上实现一致且可重复的安装，uv.lock 是一个人类可读的 TOML 文件，但由 uv 管理，不应手动编辑。

---

uv 为什么可以自动安装 Python 包

uv 通过解析 Python 脚本中的 import 语句，自动检测代码中使用了哪些外部库。

1import requests  # uv 会检测到 requests 并自动安装

当你运行：

1uv run my_script.py

如果 requests 还没有安装，uv 会自动下载安装。

uv 结合了 pip 和 virtualenv 的功能，会在执行 Python 代码前检查是否安装了所需的依赖。如果某个包不存在，它会：

1. 解析 import 语句或 requirements.txt、pyproject.toml 文件。
2. 在 uv 的依赖解析器中检查哪些包需要安装或更新。
3. 下载并安装缺失的包，而无需手动运行 pip install。

---

uv pip sync 和 uv pip install 的区别？

uv pip install

• 支持从 requirements.txt 安装（但不会卸载未使用的包）
• 增量安装：只会添加或更新包，不会清理旧的或多余的包。
• 常用于开发阶段或快速测试。

uv pip sync

• 安装 requirements.txt 中所有指定版本的包；
• 移除当前环境中不在 requirements.txt 中的多余包；
• 保证你的虚拟环境完全一致、干净

功能点	uv pip install	uv pip sync
安装新依赖	✅ 支持	✅ 支持
安装指定版本	✅（如果明确指定）	✅（锁定版本）
卸载多余依赖	❌ 不会卸载多余包	✅ 会卸载所有未在文件中定义的依赖
保证环境一致性	❌ 无法保证	✅ 强一致性
适用场景	开发调试，临时添加依赖	部署上线，CI/CD，同步统一环境

---

uv 与 pip 对应关系

功能	uv** 命令**	传统 pip/工具组合命令
编译依赖锁定文件（含版本）	uv pip compile requirements.in	pip-compile requirements.in（来自 pip-tools 工具）
同步环境（安装+卸载）	uv pip sync requirements.txt	pip-sync requirements.txt（来自 pip-tools 工具）
安装依赖（不卸载）	uv pip install	pip install
卸载依赖（手动）	uv pip uninstall	pip uninstall

安装：

1pip install pip-tools
2pip-compile requirements.in
3pip-sync requirements.txt

---

uv 安装确认是否使用了指定的镜像源

1uv pip install python-docx --verbose / -v

在输出中查找包含您指定的镜像源 URL 的信息，以确认配置是否生效。

---

uv.lock 何时会生成或更新

• 初次运行 uv add 添加依赖时自动生成；
• 修改 pyproject.toml 后再次运行 uv sync 会更新；
• 可以显式重建锁文件：uv lock