python：介绍 UV 安装，如何使用 UV 安装配置 OpenHarness

belldeep2026-04-07 9:01

UV 是一个由 Rust 编写的极速 Python 包和项目管理器，旨在成为像 Rust 的 Cargo 那样的一站式工具，解决 Python 生态中依赖管理的诸多痛点。

简单来说，UV 的目标是统一并替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv 等多个传统工具的功能。下面我为你详细介绍它。

💡 核心特点与优势

UV 的核心优势体现在以下几个方面：

  • 🚀 极致的性能 ：作为其最大亮点，UV 的依赖解析和包安装速度比 pip 快 10-100 倍 。它通过 Rust 实现并行下载和智能缓存，能显著提升开发效率和 CI/CD 流程速度。例如，有团队反馈使用 UV 后，其 CI 流水线依赖安装环节从 3 分 20 秒缩短至 18 秒。

  • 🔧 一站式工具链：UV 将项目开发所需的多种功能集成于一身，无需在多个工具间切换。它涵盖了从项目创建、依赖管理、虚拟环境控制到 Python 版本管理的完整流程。

  • 🎯 现代且简单的项目管理 ：UV 推崇"项目即环境"的理念，通过 pyproject.toml 和 uv.lock 两个核心文件来管理项目。pyproject.toml 记录项目元数据和主要依赖，而 uv.lock 则锁定所有依赖的精确版本，确保环境可复现。

  • 🤝 无缝的兼容性 ：UV 提供与 pip 和 virtualenv 兼容的命令行接口（如 uv pip install），你可以沿用熟悉的工作流，同时获得性能提升。它也支持从现有的 requirements.txt 文件迁移依赖。

⚙️ 核心功能一览

为了方便你理解，我将 UV 的主要功能模块和对应的命令整理成了表格：

功能模块 传统工具链 UV 对应命令 作用说明
项目初始化 poetry new, mkdir + 手动创建文件 uv init 在当前目录一键生成完整的 Python 项目结构，包括 pyproject.toml、README.md 等文件。
依赖管理 pip install + 手动更新 requirements.txt uv add <包名> uv remove <包名> 添加或移除项目依赖，并自动 更新 pyproject.toml 和 uv.lock 文件。
虚拟环境管理 python -m venv .venv + 手动激活 uv venv 创建虚拟环境（默认在项目根目录的 .venv 文件夹），且无需手动激活即可使用。
环境同步 pip install -r requirements.txt uv sync 根据 pyproject.toml 和 uv.lock 文件，确保当前虚拟环境与项目锁定依赖完全一致，会安装缺失的包，也会卸载多余的。
运行脚本/命令 手动激活环境后执行 python script.py uv run python script.py 在项目虚拟环境中运行脚本或命令。它会自动处理环境和依赖，无需你手动激活。
Python 版本管理 pyenv install 3.12 uv python install 3.12 uv python pin 3.11 安装和管理不同版本的 Python。uv python pin 可为当前项目固定一个特定的 Python 版本。
工具安装与运行 pipx install ruff uv tool install ruff uvx ruff check . 在隔离环境中安装或临时运行 Python 命令行工具，不会污染项目环境。uvx 是 uv tool run 的别名。

🤔 UV vs. pip vs. conda

为了帮你更清晰地选择，我对比了这三款工具：

工具 核心定位 优点 缺点 最适合场景
uv 新一代高性能 Python 包和项目管理器 极快、一站式工具链、项目环境管理现代、支持依赖锁定 生态相对较新，不支持 Conda 特有的非 Python 科学计算库 纯 Python 项目 （Web开发、脚本工具）、追求极致效率的 CI/CD 环境
pip Python 官方默认的包安装器 官方标准、兼容性极强、生态最丰富 速度慢、依赖解析能力弱、需配合其他工具管理环境和依赖 简单脚本、必须兼容老旧环境、或作为其他工具的底层依赖
conda 跨语言的系统和包管理器 擅长管理非 Python 的库（如 CUDA、MKL）、环境隔离彻底 速度最慢、非 Python 生态、环境体积大 数据科学和机器学习项目，特别是需要 GPU 加速或复杂 C/C++ 库的场景

总结一下 ：如果你是做 Web 开发、自动化脚本等纯 Python 项目，UV 能带来脱胎换骨的体验，值得优先考虑。如果项目依赖大量非 Python 的科学计算库（如 cudatoolkit），那么 Conda 仍然是不可替代的选择。

💎 上手体验

一个使用 UV 创建和运行新项目的典型流程如下：

bash 复制代码 
# 1. 初始化项目
uv init my-project
cd my-project

# 2. 添加依赖（例如 Web 框架 FastAPI）
uv add fastapi uvicorn

# 3. 运行项目（uv run 会自动使用项目环境）
uv run uvicorn main:app --reload

这个流程非常直观，uv 会在背后自动创建虚拟环境、安装并锁定依赖，而你几乎感觉不到这些步骤的存在。

⚠️ 需要注意的点

  • 生态成熟度 ：作为较新的工具，其与某些极冷门或老旧的私有 PyPI 仓库的兼容性可能不如 pip 久经考验。
  • 非 Python 依赖：UV 不能像 Conda 那样处理非 Python 的二进制依赖（如 HDF5、CUDA 驱动等）。
  • 迁移成本 ：对于已有大量 pip 工作流和脚本的团队，完全切换到 UV 需要一定的学习成本和流程改造。

uv 官方支持 Windows 11，可以顺利安装和运行。

根据你的网络情况和偏好，有几种不同的安装方式可以选择。我把最推荐的方法整理成了下面的表格，方便你对比和选择。

安装方式 适用场景 核心命令/操作 优点
PowerShell 一键安装 (推荐) 追求快速、简单，网络能访问GitHub `powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 iex"`
包管理器安装 已使用Winget、Scoop等工具管理软件 winget install --id=astral-sh.uv -e 与现有软件管理习惯统一，升级卸载方便
手动下载安装 网络访问GitHub较慢，或希望完全控制安装位置 从GitHub Releases下载uv-x86_64-pc-windows-msvc.zip并解压到自定义目录，然后将该目录添加到系统PATH环境变量 不依赖网络脚本，安装位置灵活

🔍 关键步骤详解：手动安装和环境配置

如果你选择"手动下载安装"，或在一键安装后需要进行配置，可以关注以下几点：

  1. 下载正确的文件 ：访问 uv的GitHub Releases页面，为64位的Windows 11系统下载名为 uv-x86_64-pc-windows-msvc.zip 的压缩包。
  2. 添加到PATH环境变量 ：将解压得到的 uv.exe 所在文件夹路径（例如 D:\soft\uv 或 C:\tools\uv）添加到系统的 PATH 环境变量中。这样你就可以在任意目录下的命令行中直接使用 uv 命令了。
    • 小提示 ：配置完环境变量后，需要重新打开一个新的命令行窗口（PowerShell 或 CMD），配置才会生效。
  3. 配置国内源（可选但强烈推荐） ：如果你在中国大陆，为uv配置国内镜像源可以极大地提升下载Python包的速度。可以通过设置环境变量来实现：
    • 变量名 ：UV_DEFAULT_INDEX
    • 变量值 ：https://pypi.tuna.tsinghua.edu.cn/simple/ （这是清华大学镜像源，你也可以替换为其他镜像）

✅ 验证安装

打开一个新的PowerShell或命令提示符窗口，输入以下命令并回车：

bash 复制代码 
uv --version

如何使用 UV 安装配置 OpenHarness ?

用 uv 安装 OpenHarness 比 pip 更快、环境更干净。下面是完整、可直接复制的步骤（Windows/macOS/Linux 通用）。

一、先安装 uv（包管理器）

macOS / Linux

bash 复制代码 
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell, 管理员)

powershell 复制代码 
irm https://astral.sh/uv/install.ps1 | iex

验证

bash 复制代码 
uv --version
# 应出现 uv 0.4x.x

二、用 uv 安装 OpenHarness（两种方式）

方式1：全局安装（最简单，推荐）

bash 复制代码 
uv tool install openharness

验证：

bash 复制代码 
oh --version
# OpenHarness v0.1.x

方式2：源码安装（开发/魔改用）

bash 复制代码 
git clone https://github.com/HKUDS/OpenHarness.git
cd OpenHarness

# 用 uv 创建虚拟环境并安装所有依赖
uv sync --extra dev

激活环境：

bash 复制代码 
# macOS/Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

三、配置 API Key（必做）

方法A：环境变量（推荐）

bash 复制代码 
# OpenAI
export OPENAI_API_KEY="sk-xxxx"

# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-xxxx"

# 本地 Ollama
export OLLAMA_API_BASE=http://localhost:11434

方法B：配置文件

bash 复制代码 
cp config.example.yaml config.yaml

编辑 config.yaml：

yaml 复制代码 
llm:
  provider: openai          # openai / anthropic / ollama / moonshot
  api_key: sk-xxxxxxxxxxxx
  model: gpt-3.5-turbo
  base_url: https://api.openai.com/v1

四、一键启动

全局安装（直接用）

bash 复制代码 
oh

源码安装（虚拟环境内）

bash 复制代码 
uv run oh
# 或直接
oh

启动后即可输入指令：

复制代码 
列出当前目录
创建一个hello.py并运行

五、uv 常用命令（对比 pip）

任务 pip 命令 uv 命令
安装包 pip install openharness uv tool install openharness
从requirements安装 pip install -r requirements.txt uv pip install -r requirements.txt
创建虚拟环境 python -m venv .venv uv venv
同步依赖 --- uv sync
运行脚本 python main.py uv run python main.py

六、常见问题

  • uv: command not found

    重启终端，或手动添加 PATH：

    bash 复制代码 
    echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

  • 依赖安装失败

    bash 复制代码 
    uv sync --clean  # 清理缓存重装

下面给你一套Windows 11 + Ollama + uv + OpenHarness 的纯本地、完全离线可用的完整配置流程，一步不差照着做就能跑起来。

0. 前提

  1. 你已经装好了 Ollama 并能正常运行

  2. 已经拉取了一个模型，例如：

    powershell 复制代码 
    ollama pull qwen2.5:7b
# 或 llama3.1:8b、gemma2:9b 等

1. 安装 uv（Windows 11 PowerShell）

以普通用户 PowerShell运行：

powershell 复制代码 
irm https://astral.sh/uv/install.ps1 | iex

安装完关闭并重新打开一个新的 PowerShell，再执行：

powershell 复制代码 
uv --version

能显示版本号就成功。

2. 下载 OpenHarness 源码

powershell 复制代码 
git clone https://github.com/HKUDS/OpenHarness.git
cd OpenHarness

没有 git 就去官网下 zip 解压，然后进入文件夹。

3. 用 uv 创建环境 + 安装依赖

powershell 复制代码 
# 创建虚拟环境
uv venv

# 激活环境
.venv\Scripts\Activate.ps1

然后安装依赖：

powershell 复制代码 
uv pip install -r requirements.txt

4. 配置 Ollama（关键）

复制配置文件：

powershell 复制代码 
cp config.example.yaml config.yaml

用记事本/VSCode 打开 config.yaml，全部替换成下面内容：

yaml 复制代码 
llm:
  provider: ollama
  model: qwen2.5:7b          # 你本地实际的模型名
  base_url: http://localhost:11434
  api_key: "_"               # Ollama 不需要 key，随便填

agent:
  max_iterations: 10
  auto_confirm: false        # 执行文件/命令前是否需要你确认

memory:
  enable_persistent: true
  path: ./memory

security:
  allowed_paths:
    - ./workspace
    - .
  forbidden_commands:
    - rm -rf /
    - format
    - del /f /s /q C:\

模型名必须和你 ollama list 里一模一样。

5. 启动 OpenHarness

确保 Ollama 正在后台运行，然后执行：

powershell 复制代码 
uv run python main.py

出现交互式终端就成功了。

6. 测试一下（直接输入）

复制代码 
查看当前目录有什么文件

新建一个 test.py，打印 hello world 并运行

它会：

  • 调用 Ollama 本地模型思考
  • 使用内置工具读写文件、执行命令
  • 完全不联网

7. 常用快捷命令（Windows）

powershell 复制代码 
# 下次进入项目，快速激活环境
cd OpenHarness
.venv\Scripts\Activate.ps1

# 启动
uv run python main.py
相关推荐
杜子不疼.2 小时前
Python + Ollama 本地跑大模型：零成本打造私有 AI 助手
开发语言·c++·人工智能·python
李昊哲小课2 小时前
pip缓存配置
python·缓存·pip
理想三旬2 小时前
Numpy 数据库
python·机器学习·numpy
波诺波2 小时前
p3项目-模拟 PID 控制器用来调节直流电机的转速
python·pid
路飞雪吖~2 小时前
【测试】接口测试---1个框架，5个模块
开发语言·python·测试工具
q_35488851532 小时前
计算机毕业设计：Python居民出行规律可视化分析系统 Django框架 可视化 数据分析 PyEcharts 交通 深度学习（建议收藏）✅
人工智能·python·数据分析·车载系统·django·汽车·课程设计
FL16238631292 小时前
基于yolov26的荔枝成熟度检测系统python源码+pytorch模型+评估指标曲线+精美GUI界面
pytorch·python·yolo
iuu_star2 小时前
宝塔Linux部署python常遇问题解决
开发语言·python·腾讯云
Dream of maid2 小时前
Python基础4（函数）
开发语言·python
热门推荐
01GitHub 镜像站点02OpenClaw 请求超时 llm request timed out 怎么解决？3 种方案实测，附完整排查流程03Qwen3.5-Omni与Qwen3.6模型全面解析（含测评/案例/使用教程）04VMware Workstation Pro 17 虚拟机完整安装教程（2026最新）05AI 编程效率翻倍：Superpowers Skills 上手清单 + 完整指南06最新更新版本，OpenClaw v2026.4.2 深度解读剖析：Task Flow 重磅回归与安全架构的全面硬化07【技术干货】Gemma 4 上手深度指南：本地多模态大模型的新基线08Claude Code 未登录 使用第三方模型09纯 HTML/CSS/JS 实现的高颜值登录页，还会眨眼睛！少女心爆棚！10UV安装并设置国内源