Python包与环境管理工具uv介绍

🍎 uv与传统pip的对比

简单来说，uv（使用rust开发）保留了 pip（使用python开发） 的所有优点，同时解决了 pip 速度慢、功能单一、稳定性差的核心痛点，是未来 Python 包管理的主流方向。

🍎 uv常用的文件及其作用

1. uv.toml - UV配置文件

• 作用 ：配置uv包管理器的行为，如镜像源设置
• 内容 ：比如可以配置使用清华大学的PyPI镜像源 https://pypi.tuna.tsinghua.edu.cn/simple
• 意义 ：加速包下载，特别是在国内网络环境下

2. uv.lock - 依赖锁定文件

• 作用 ：锁定所有依赖包的精确版本，确保环境一致性
• 内容 ：包含项目所有依赖包的精确版本信息，如：
  • openai <=1.99.1
  • langchain >=0.3.27
  • llama-index >=0.10.0
• 意义 ：确保在不同机器上安装时获得完全相同的依赖版本

🍎 常用命令

✅ 基本操作命令

# mac安装uv 编译起来有点慢
brew install uv

# 升级uv版本（最新版本的uv，我的macOS-13 不兼容！）
uv self update

# uv的版本
uv --version
'''
uv 0.9.5 (Homebrew 2025-10-21)
'''

# 查看 uv 的本地缓存目录
uv cache dir

# 清理 uv 本地缓存（避免缓存的失效源信息）
uv cache clean

# 使用uv安装python
uv python install 3.15

# 使用uv查看python的版本
uv python list

# 指定目录与Python版本创建虚拟环境
uv venv ~/venvs/uv_ai_agent_311 --python 3.11
'''
Using CPython 3.11.11 interpreter at: /opt/homebrew/opt/python@3.11/bin/python3.11
Creating virtual environment at: uv_ai_agent_311
Activate with: source uv_ai_agent_311/bin/activate
'''

# 激活虚拟环境
source ~/venvs/uv_ai_agent_311/bin/activate

# 退出虚拟环境
deactivate

❗️依赖管理命令

❗️❗️❗️注意下，使用uv就不用安装pip了，uv不用pip管理包！！！这是uv比传统虚拟环境快的原因！

### 使用阿里云镜像同步（根据pyproject.toml或requirements.txt
### 另外还受 uv.lock 与 uv.toml 文件的影响）


#❗️❗️注意：uv sync 默认安装到项目根目录的 ".venv" 目录！加上 --active 参数可以将模块与包安装到之前激活的虚拟环境的目录！
uv sync --active --index https://mirrors.aliyun.com/pypi/simple/


# 安装单个包（没怎么用到过，后面用到再研究下～）
'''
uv add package_name
# 安装开发依赖（没怎么用）
uv add --dev package_name
# 更新所有依赖（没怎么用）
uv sync --upgrade
'''

### 查看已安装的包
uv pip list
'''
Using Python 3.11.11 environment at: /Users/wanghongwei/venvs/ai_agent_311
（下面什么也没有）
'''

### 使用 uv pip 安装第三方模块
 uv pip install redis
  '''
  Using Python 3.11.11 environment at: uv_ai_agent_311
  Resolved 1 package in 1.51s
  Prepared 1 package in 15.78s
  Installed 1 package in 6ms
   + redis==7.1.0
  '''
### 使用 uv 卸载三方包
uv pip uninstall redis
'''
Using Python 3.11.11 environment at: uv_ai_agent_311
Uninstalled 1 package in 11ms
 - redis==7.1.0
'''


##### ❗️应该怎么做 可以把 uv sync 安装的模块放到 当前激活的虚拟环境的位置呢？下面是AI的解答，但是需要验证下！！！

✅ uv sync 将安装的模块放到当前激活的虚拟环境的位置

❗️方案 1：单次命令（临时生效，推荐调试 / 单次使用）

执行 uv sync 时添加 --active 参数，强制 uv 识别并安装到当前激活的虚拟环境（日志中 VIRTUAL_ENV 指向的路径）：

# 核心命令：--active 绑定当前激活的虚拟环境
uv sync --active --index https://mirrors.aliyun.com/pypi/simple/

# 验证：安装后立即查看当前环境的依赖
uv pip list | grep -E "(openai|langchain|faiss)"
'''
# 输出:
faiss-cpu                               1.7.4
langchain                               0.3.27
langchain-community                     0.3.27
langchain-core                          0.3.74
langchain-openai                        0.3.29
langchain-text-splitters                0.3.9
llama-index-embeddings-openai           0.5.0
llama-index-llms-openai                 0.5.2
llama-index-llms-openai-like            0.5.0
openai                                  1.99.1
'''

• 原理：--active 会让 uv 忽略项目默认的 .venv，优先使用 $VIRTUAL_ENV 环境变量指向的激活环境；
• 适用场景：临时适配现有激活的环境，无需修改配置。

❗️方案 2：项目级配置（仅当前项目生效，推荐团队协作）

若仅想让某个项目的 uv sync 安装到激活环境，在项目根目录的 uv.toml 中配置（不影响全局）：

步骤 1：在项目根目录创建 / 编辑 uv.toml

# 项目根目录 uv.toml
[env]
# 该项目优先使用激活的虚拟环境
prefer-active-env = true

# 保留项目的镜像源配置（可选）
[index]
default = "https://mirrors.aliyun.com/pypi/simple/"
index-only = true

步骤 2：执行同步

# 直接执行，自动安装到激活环境
uv sync

❗️关键补充：验证安装路径

执行完 uv sync 后，通过以下命令确认依赖已安装到激活环境：

# 1. 查看当前激活环境的路径
echo $VIRTUAL_ENV  # 输出：/Users/wanghongwei/venvs/ai_agent_311

# 2. 检查依赖是否存在于该环境的 site-packages
ls $VIRTUAL_ENV/lib/python3.11/site-packages | grep openai

# 3. 通过 uv 确认环境匹配
uv env info
# 输出中 "Active environment" 和 "Project environment" 应指向同一路径（激活的环境）

❗️核心原理总结

配置方式	参数 / 配置项	效果	适用场景
单次命令	--active	临时绑定激活环境，仅本次命令生效	调试、临时切换环境
全局配置	prefer-active-env = true	所有项目默认使用激活环境	个人开发环境统一配置
项目级配置	prefer-active-env = true	仅当前项目使用激活环境	团队协作、项目专属配置

❗️避坑提醒

1. 若执行

   uv sync --active
   

   仍安装到

   .venv
   

   先删除项目根目录的.venv

   rm -rf .venv
   

   再重新执行（避免残留环境干扰）；

2. 确保虚拟环境真的激活：

   执行

   source /Users/wanghongwei/venvs/ai_agent_311/bin/activate
   

   后，再执行

   uv sync
   

3. 版本兼容：prefer-active-env是 uv 0.1.30+ 新增的配置，若 uv 版本过低，先升级：

   uv self update
   

方案 3：全局配置（需要比较新的uv版本）

❗️我本地装的uv版本比较低，用不了这个～而且我的macOS系统是13版本的，升级uv会有不兼容的问题！

修改 uv 全局配置文件，让所有 uv sync 命令默认安装到激活环境（替代项目 .venv）：

步骤 1：打开 / 创建 uv 全局配置文件

# macOS/Linux 全局配置路径
vim ~/.config/uv/uv.toml

# Windows 全局配置路径（PowerShell）
notepad $env:APPDATA/uv/uv.toml

步骤 2：添加环境优先级配置

写入以下内容，强制 uv 优先使用激活的虚拟环境：

# ~/.config/uv/uv.toml
[env]
# 优先使用当前激活的 VIRTUAL_ENV，而非项目 .venv
prefer-active-env = true

# 可选：保留你的镜像源全局配置
[index]
default = "https://mirrors.aliyun.com/pypi/simple/"
trusted-host = ["mirrors.aliyun.com"]
timeout = 60

步骤 3：生效验证

保存后，直接执行 uv sync 即可自动安装到激活环境：

# 无需加 --active，默认安装到激活环境
uv sync
# 查看依赖
uv pip list | grep openai