📘 uv 包管理器与 Python 虚拟环境操作文档
一、核心概述
本文档整合了 uv 安装 → Python 环境管理 → 虚拟环境创建 → IDE 关联 的完整流程，适用于 Windows 系统，用于高效管理 Python 项目环境，避免依赖冲突。
二、uv 包管理器安装
1. 安装触发
在 ByteIDE（Tree）中首次运行 Python 代码时，若提示 No Python found，点击弹窗中的 Install Python，IDE 会自动下载并安装 uv 工具。
2. 验证安装
安装完成后，打开终端（IDE 内置终端或系统 CMD），输入以下命令验证 uv 是否可用：
uv --version
若输出版本号（如 uv 0.4.0），说明安装成功。
三、用 uv 管理 Python 版本
1. 安装指定 Python 版本
在终端执行以下命令，安装 Python 3.13 版本（可替换为其他版本，如 3.12）：
uv python install 3.13
uv 会自动下载并配置 Python 环境，无需手动处理环境变量。
2. 查看已安装 Python 版本
uv python list
终端会列出所有通过 uv 安装的 Python 版本，标记 * 的为当前默认版本。
3. 卸载系统全局 Python（可选）
若需彻底隔离环境，可卸载系统中已安装的全局 Python：
- 打开「设置 → 应用 → 安装的应用」，找到 Python 条目，点击「卸载」
- 卸载完成后重启电脑，确保环境变量清理干净
四、创建并激活虚拟环境
1. 进入项目目录
在终端中切换到你的 Python 项目文件夹（示例路径）：
cd C:\Users\HI\Desktop\pyeco
2. 创建虚拟环境
执行以下命令，在项目目录下生成独立虚拟环境（默认命名 .venv）：
uv venv
执行后项目目录会出现 .venv 文件夹，包含独立的 Python 解释器和依赖库。
3. 激活虚拟环境
- Windows CMD 终端：
.venv\Scripts\activate - Windows PowerShell 终端：
.venv\Scripts\Activate.ps1
激活成功后，终端前缀会显示虚拟环境名称（如 (pyeco)）。
4. 验证虚拟环境 Python 版本
python --version
若输出与 uv python list 中一致的版本号（如 Python 3.13.12），说明虚拟环境可用。
五、在 ByteIDE（Tree）中关联虚拟环境
1. 打开解释器选择面板
点击 IDE 右下角的 Select Python Interpreter。
2. 选择虚拟环境解释器
在弹出的列表中，选择项目目录下的路径：
C:\Users\HI\Desktop\pyeco\.venv\Scripts\python.exe
若列表中未显示，可点击 Browse... 手动定位该路径。
3. 验证关联结果
关联完成后，IDE 右下角会显示当前激活的环境（如 Python 3.13.12 64-bit (.venv)），此时运行代码将使用该虚拟环境，不会出现环境报错。
六、依赖包管理（拓展）
1. 安装依赖包
在激活虚拟环境的终端中，使用 uv pip 安装包（比传统 pip 更快）：
uv pip install requests # 示例：安装 requests 库
2. 导出依赖清单
将当前环境依赖导出为 requirements.txt，便于项目迁移：
uv pip freeze > requirements.txt
3. 从清单恢复环境
在新设备或新虚拟环境中，执行以下命令恢复依赖：
uv pip install -r requirements.txt
七、常见问题排查
| 问题现象 | 解决方案 |
|---|---|
No base python found |
执行 uv python install 3.13 安装 Python 版本 |
Unable to handle 解释器错误 |
删除 .venv 文件夹，重新执行 uv venv 重建虚拟环境 |
终端中 uv 命令不可用 |
重启终端/IDE，或手动将 uv 安装目录添加到系统环境变量 |
| 虚拟环境激活后 Python 版本不对 | 检查 uv python list，确保默认版本正确，或重新创建虚拟环境 |
八、操作流程速记（极简版）
# 1. 安装 uv（IDE 弹窗触发）
# 2. 安装 Python
uv python install 3.13
# 3. 进入项目目录
cd 你的项目路径
# 4. 创建虚拟环境
uv venv
# 5. 激活虚拟环境
.venv\Scripts\activate
# 6. IDE 关联 .venv/Scripts/python.exe
# 7. 运行代码 / 安装依赖