uv管理虚拟环境

最近在推agent应用开发，而agent开发中，与MCP等搭配最主流的最佳虚拟环境实践是uv，因此在此记录uv使用。可以把uv看作是venv或virtualenv的现代化替代。本文仅讨论LInux或Mac环境。

一、安装

在Mac和Linux中可以用curl或wget来安装：
curl -LsSf https://astral.sh/uv/install.sh | sh
wget -qO- https://astral.sh/uv/install.sh | sh
curl -LsSf https://astral.sh/uv/0.10.6/install.sh | sh

pip也可以安装：
pipx install uv
pip install uv

安装后查看uv版本：uv --version

卸载uv：
uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"
rm ~/.local/bin/uv ~/.local/bin/uvx

更新uv：uv self update

二、基本使用

安装和管理 Python 本身。

• uv python install 3.13安装 Python 版本。
• uv python list查看可用的 Python 版本。
• uv python find 3.13查找已安装的 Python 版本。
• uv python pin 3.13将当前项目锁定为使用特定的 Python 版本。
• uv python uninstall 3.13卸载 Python 版本。
  

执行独立的 Python 脚本，例如example.py：

• uv run运行脚本。
• uv add --script：向脚本添加依赖项。
• uv remove --script移除脚本中的依赖项。

创建项目的虚拟环境：

有两种方式，第一种是先创建项目目录，cd到其中然后设置python版本，并初始化uv虚拟环境：uv python pin 3.13    uv init
第二种是在init后面加上项目名，会自动创建项目文件夹：uv init mypro

完整管理项目：

首先需要说明的是，uv兼容了pip，venv等传统的虚拟环境方式，可以使用uv pip install xxx1 xxx2来安装库，这条命令

• 在当前激活的虚拟环境中安装最新版的xxx1和xxx2；
• 不修改任何项目配置文件；
• 不生成或更新锁文件；
• 仅影响当前环境。

uv 会自动管理虚拟环境，通常无需手动运行 uv venv 或 source .venv/bin/activate。

uv add 是 uv 为现代 Python 项目量身打造的 高层 API，与 uv init、uv run、uv sync、uv lock 等命令一起构成完整的项目管理闭环。uv 支持 pyproject.toml 格式的项目管理，这是现代 Python 项目的标准配置文件。
uv init                              # 初始化项目（生成 pyproject.toml）
uv add polars marimo    # 添加依赖
uv run python app.py    # 在正确环境中运行脚本

执行 uv add 后，uv 会：
自动将依赖写入 pyproject.toml 的 [project.dependencies] 或 [tool.uv] 中；
执行一次 通用解析（universal resolution），确保所选版本在所有目标平台（Windows/Linux/macOS）、架构和 Python 版本上都可用；
生成或更新 uv.lock 锁文件，锁定精确的依赖树。任何人克隆项目后只需安装项目的依赖uv sync 即可复现环境（这个命令会根据 pyproject.toml 和 requirements.txt 安装所有依赖，类似于 pip install -e . 但更高效）。

说明：

uv sync 是一个依赖管理命令，它的作用类似于您可能更熟悉的 pip install -r requirements.txt，但更快、更强大、更可靠。
您可以把它理解为："一键安装这个项目正常运行所需的所有第三方软件包（依赖库）"。
uv sync 如果安装太慢，可以设置国内镜像源 https://pypi.tuna.tsinghua.edu.cn/simple：
在项目根目录的 pyproject.toml 文件 [tool.uv] 处设置 index-url：

[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"