uv

UV - Python 包管理器技能

概述

UV 是一款使用 Rust 编写、速度极快的 Python 包和项目管理器。本技能介绍如何使用 UV 进行 Python 开发，特别关注 MCP（Model Context Protocol）服务集成和现代工具管理工作流。

UV 可取代多种工具：pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等。通过智能缓存和并行操作，速度可提升 10-100 倍。

版本说明

推荐版本：UV 0.9.7+（截至 2025 年 10 月的最新版本）

开始前，请检查 UV 版本：

uv --version

特定版本的重要变更：

• UV 0.9.6+：Python 3.14 现为默认版本（此前为 3.13）
• UV 0.9.6+：支持自由线程的 Python 3.14+，无需显式启用
• UV 0.9.6+：新增 uv build --clear 标志，可用于清理构建产物
• UV 0.9.7+：针对 tar/ZIP 归档处理的安全更新

如果你的版本低于 0.9.0，建议升级以获得最佳体验：

# Using pip
pip install --upgrade uv

# Or reinstall using official installer
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Unix/Mac
curl -LsSf https://astral.sh/uv/install.sh | sh

有关版本信息和迁移指南的详细说明，请参阅近期变更参考。

何时使用本技能

在以下情况下使用本技能：

• 创建 Python 虚拟环境和管理 Python 版本
• 安装和管理 Python 命令行工具（开发工具、实用程序）
• 使用 UVX 运行 MCP 服务
• 决定使用 uv tool install 还是 uvx 执行包
• 为 MCP 服务集成配置 VS Code 或其他 IDE
• 从 pip、pipx 或 poetry 迁移到 UV
• 排查与 UV 相关的问题

以下情况下无需使用本技能：

• 你只需安装基础 Python 包（标准 pip 文档可能就够用）
• 使用旧版 Python 2.x 项目

核心概念

1. UV 命令概览

UV 提供了适用于不同场景的多种命令：

命令	用途	示例
uv pip install	在当前环境中安装包	uv pip install requests
uv tool install	在全局隔离环境中安装 CLI 工具	uv tool install black
uvx	在临时环境中执行包	uvx mcp-server-sqlite
uv venv	创建虚拟环境	uv venv .venv
uv python install	安装 Python 版本	uv python install 3.12

2. Tool 与 UVX 选择流程

Need to run a Python package?
|
├─ Use daily/frequently?
|  └─ YES → `uv tool install package`
|     Examples: black, pytest, flake8, mypy
|
├─ MCP server?
|  └─ YES → `uvx package` or `uvx --from path script.py`
|     Examples: mcp-server-sqlite, custom MCP servers
|
├─ Testing/one-off execution?
|  └─ YES → `uvx package`
|     Examples: testing new tools, version comparison
|
└─ Local development script?
   └─ YES → `uvx --from . script.py`
      Examples: project-specific scripts

3. MCP 服务运行模式

已发布的包（无需工作目录）：

{
  "servers": {
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "/path/to/db"]
    }
  }
}

本地开发（使用 --from 标志）：

{
  "servers": {
    "my-server": {
      "command": "uvx",
      "args": [
        "--from", "/absolute/path/to/project",
        "server.py",
        "--config", "config.json"
      ]
    }
  }
}

关键要点：--from 标志就是 UVX 的工作目录引用。

4. 虚拟环境管理

UV 与 Python 内置的 venv 无缝协作：

# Create virtual environment
python -m venv .venv

# Activate (Windows Git Bash)
. .venv/Scripts/activate

# Activate (Windows CMD)
.venv\Scripts\activate.bat

# Activate (Linux/Mac)
source .venv/bin/activate

# Install packages with UV
uv pip install -r requirements.txt

常见工作流

开发工具设置

# Install development tools once
uv tool install black
uv tool install flake8
uv tool install mypy
uv tool install pytest

# Use daily
black .
flake8 src/
mypy src/
pytest tests/

MCP 服务使用

# Test published MCP servers
uvx mcp-server-sqlite --db-path test.db
uvx mcp-server-git --repository /path/to/repo

# Local MCP server development
uvx --from /path/to/project server.py --env config.env

项目初始化

# Create new project with UV
uv init my-project
cd my-project

# Add dependencies
uv add requests fastapi

# Run project
uv run python main.py

Python 版本管理

# List available Python versions
uv python list

# Install default Python version (3.14 in UV 0.9.6+)
uv python install

# Install specific Python version
uv python install 3.12
uv python install 3.13

# Use in project
uv python pin 3.12

**注意：**截至 UV 0.9.6，Python 3.14 是默认版本。如果需要使用 Python 3.13 或更早版本，请显式指定版本。

内联脚本依赖（PEP 723）

UV 支持直接在 Python 脚本注释中定义依赖：

# /// script
# dependencies = [
#   "requests",
#   "pandas",
# ]
# ///

import requests
import pandas as pd

# Your code here

运行脚本并自动安装依赖：

# UV installs dependencies automatically
uv run script.py

优点：

• 独立的单文件脚本
• 无需 pyproject.toml
• 易于共享和分发
• 非常适合实用程序和自动化任务

如需查看全面的示例，包括 MCP 服务、Web 应用、数据处理和 CLI 工具，请参阅内联脚本元数据参考。

集成模式

VS Code MCP 配置

用于 .vscode/mcp.json 或用户设置：

{
  "servers": {
    "published-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "${workspaceFolder}/db.sqlite"]
    },
    "local-dev": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "${workspaceFolder}",
        "src/server.py"
      ]
    }
  }
}

Continue IDE 配置

用于 .continue/config.json：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": ["mcp-server-fetch"]
        }
      }
    ]
  }
}

GitHub Actions CI/CD

- name: Setup UV
  uses: astral-sh/setup-uv@v1

- name: Install dependencies
  run: uv pip install -r requirements.txt

- name: Run tests
  run: uv run pytest

最佳实践

工具管理

应该：

• 对于频繁使用的开发工具，使用 uv tool install
• 对于 MCP 服务，使用 uvx（遵循社区惯例）
• 让工具在各自独立的环境中运行
• 定期使用 uv tool upgrade --all 升级工具

不应该：

• 使用全局 pip 安装命令行工具（会导致依赖冲突）
• 使用 uv tool install 安装 MCP 服务（不符合社区惯例）
• 将 uvx 用于日常开发工具（会造成不必要的开销）
• 混用 pip 和 uv 工具安装方式

MCP 服务模式

应该：

• 所有 MCP 服务都使用 UVX 执行
• 本地开发时使用 --from
• 为生产环境固定版本（[email protected]）
• 使用环境变量进行配置

不应该：

• 全局安装 MCP 服务
• 混用工作目录方式
• 在生产环境中使用 @latest（不稳定）
• 忘记使用 --from 指定绝对路径

虚拟环境

应该：

• 使用 python -m venv 创建项目环境
• 安装软件包前先激活环境
• 使用 uv pip install 加快软件包安装
• 在 README 中记录激活命令

不应该：

• 全局安装软件包
• 混用 venv 和系统 Python 软件包
• 忘记在开发前激活环境
• 将 .venv 目录提交到版本控制

性能特征

UV 的性能优势：

• 软件包操作速度比 pip 快 10-100 倍
• 并行下载和安装
• 支持去重的全局缓存
• 由 Rust 驱动的依赖解析
• 通过硬链接实现高效的磁盘存储

典型操作耗时：

• 软件包安装：速度比 pip 快 100-1000 倍
• 依赖解析：缓存的软件包可近乎即时完成
• 创建虚拟环境：<1 秒
• UVX 首次运行：软件包下载时间 + 执行时间
• UVX 缓存后运行：启动时间 <1 秒

故障排查

常见问题

“spawn uvx ENOENT”错误：

• UV/UVX 不在 PATH 中
• 解决方案：重新安装 UV，或手动将其添加到 PATH

找不到软件包：

• 在 PyPI 上检查软件包名称
• 对于本地开发，请验证 --from 路径
• 确保 pyproject.toml 存在

权限错误：

• UV 缓存目录不可写
• 解决方案：检查 ~/.cache/uv/ 的权限

版本冲突：

• 存在多个 Python 版本
• 解决方案：使用 uv python pin 设置项目版本

详细的故障排查信息见：

• 安装与设置参考
• 工具管理参考
• MCP 集成参考

参考文档

此技能包含详细的参考文档：

1. 近期变更 ⭐ 新增

   • 最新版本信息（0.9.7+）
   • Python 3.14 默认版本及自由线程支持
   • 新功能和重大变更
   • 版本兼容性矩阵
   • 升级指南

2. 安装与设置

   • 安装方法（Windows、Linux、Mac）
   • 虚拟环境设置
   • 平台特定注意事项

3. 工具管理

   • UV tool install 与 UVX 对比
   • 持久执行与临时执行
   • 维护工作流

4. MCP 集成

   • 已发布软件包的模式
   • 使用 --from 进行本地开发
   • VS Code 和 IDE 配置

5. Python 环境

   • Python 版本管理
   • 系统路径（pyenv、uv、系统）
   • 跨平台兼容性

6. 内联脚本元数据

   • 注释中的 PEP 723 内联依赖
   • 带自动依赖管理的单文件脚本
   • MCP 服务、Web 应用和命令行工具
   • 最佳实践和故障排查

7. 示例

   • 真实世界的 GitHub 配置
   • 常见工作流模式
   • 应避免的反模式

外部资源

• UV 官方文档：https://docs.astral.sh/uv/
• UV GitHub 仓库：https://github.com/astral-sh/uv
• MCP 官方文档：https://modelcontextprotocol.io/
• MCP 服务仓库：https://github.com/modelcontextprotocol/servers
• VS Code MCP 支持：https://code.visualstudio.com/docs/copilot/chat/mcp-servers

迁移指南

从 pip 迁移

# Old way
pip install requests

# New way
uv pip install requests

从 pipx 迁移

# Old way
pipx install black

# New way
uv tool install black

从 poetry 迁移

# Old way
poetry add requests
poetry install

# New way
uv add requests
uv sync

总结

UV 提供了一种统一、快速且现代的 Python 包管理方式。有效使用 UV 的关键在于：

1. 了解工具体系：uv pip、uv tool 和 uvx 各有特定用途
2. 遵循社区惯例：MCP 服务使用 UVX，开发工具使用 uv tool
3. 利用隔离机制：每个工具都拥有独立环境，避免发生冲突
4. 使用 --from 进行本地开发：这是开发 MCP 服务的必备模式
5. 保持工具更新：定期维护可避免问题

遵循这些惯例并使用参考文档，你将拥有一个整洁、高效且易于维护的 Python 开发环境。