小白的uv包管理工具使用

`uv` 是由 **Astral**（开发了 Ruff、Rye 等知名 Python 工具的团队）于 2024 年推出的一个**超高速 Python 包安装器和解析器**，旨在**替代 pip、pip-tools、virtualenv、poetry install 等传统工具的部分功能**，并以极致的速度和兼容性为目标。

特性	uv	pip	Poetry
主要定位	高性能包安装器与依赖解析器	官方基础包安装工具	全功能项目与依赖管理工具
语言实现	Rust	Python	Python
安装速度	极快（10–100 倍于 pip）	慢（单线程为主）	中等（依赖解析较慢）
依赖解析	支持确定性解析，生成锁定文件	无完整依赖解析，子依赖可能漂移	支持确定性解析，生成 poetry.lock
虚拟环境管理	内置 uv venv	不支持，需配合 venv/virtualenv	自动创建和管理
锁定文件支持	支持（通过 uv pip compile 生成 requirements.txt）	不支持	支持（poetry.lock）
同步环境（卸载多余包）	支持（uv pip sync）	不支持	支持（poetry install 自动同步）
项目元数据管理	不支持	不支持	支持（作者、版本、入口点等在 pyproject.toml 中定义）
包发布（上传到 PyPI）	不支持	需配合 twine 等工具	支持（poetry publish）
配置文件格式	兼容 requirements.txt、pyproject.toml 等标准格式	同左	使用自定义风格的 pyproject.toml
与现有生态兼容性	高（命令模仿 pip，无缝替换）	最高（官方标准）	中（锁定文件格式私有，与 requirements.txt 不直接互通）
学习成本	低（类似 pip）	极低	中高（需理解其工作流）
适用场景	CI/CD 加速、Docker 构建、快速环境搭建	快速试用、简单脚本、底层依赖	开发可发布包、中大型项目、团队协作

UV包工具快速使用

1. UV的安装

已安装python

pip install uv 

未安装python

curl -LsSf https://astral.sh/uv/install.sh | sh #下载到/usr/local/bin

2. UV的常见指令

uv init name           # uv初始化，生成name文件夹
uv add name            # 安装name插件
uv venv --python 3.12  # 生成虚拟环境并指定python版本
uv remove              # 从项目中删除依赖项。    
uv sync                # 将项目的依赖项与环境同步。    
uv lock                # 为项目的依赖项创建一个 lockfile。    
uv run                 # 在项目环境中执行命令。    
uv tree                # 查看项目的依赖关系树。    
uv build               # 将项目构建到分发存档中。    
uv publish             # 将项目发布到包索引。

UV包管理工具的结构

1. .gitignore

• 作用：告诉 Git 哪些文件或目录不需要纳入版本控制。（在.gitignore存在的所有文件都不纳入版本控制）

• 在 uv 项目中的典型内容：

# Python-generated files
__pycache__/
*.py[oc]
build/
dist/
wheels/
*.egg-info

# Virtual environments
.venv

虽然 uv 默认创建的虚拟环境名为 .venv（位于项目根目录），但你可以通过 uv venv --name myenv 指定其他名称。为避免将本地环境提交到仓库，必须在 .gitignore 中排除虚拟环境目录。

1. .python-version

• 作用：记录项目所需的 Python 版本号（如 3.11.9）。

• 来源：该文件通常由 pyenv 或 rye 等 Python 版本管理工具读取。

• 与 uv 的关系：
  uv 本身不读取 .python-version，但开发者常配合 pyenv 使用：

  • pyenv 根据此文件自动切换 Python 版本；

  • uv 在该 Python 环境下创建虚拟环境并安装依赖。

1. main.py

• 作用：项目的主入口脚本。

• 与 uv 无直接关联，但 uv 安装的依赖可在此文件中被导入使用。

• 说明：
  uv 不关心你的代码结构，只负责管理依赖。你可以有 main.py、app/ 目录、src/ 布局等任意形式。

1. pyproject.toml

• 作用：核心配置文件，定义项目的依赖、元数据、构建后端等。

• 在 uv 工作流中的关键角色：

  • uv 会读取其中的 [project.dependencies] 和 [project.optional-dependencies] 来安装依赖；

  • 支持 PEP 621 标准格式，与 Poetry、Hatch、setuptools 等工具兼容；

  • 可替代传统的 requirements.txt（更结构化、支持开发依赖分组）。

  [project]
  name = "mcp-client"
  version = "0.1.0"
  description = "Add your description here"
  readme = "README.md"
  requires-python = ">=3.13"
  dependencies = [
      "httpx>=0.28.1",
      "mcp>=1.25.0",
      "openai>=2.14.0",
      "python-dotenv>=1.2.1",
  ]
  

uv的使用依赖的方法

uv pip install -e .  # 安装当前项目及其依赖（含开发依赖需加 -e .[dev]）
uv pip compile pyproject.toml -o requirements.txt  # 生成锁定文件

1. README.md

• 作用：项目说明文档，介绍功能、安装步骤、使用方法等。