开始使用uv作为python的包管理器

最近在开发MCP Server时，注意到MCP官方Python教程推荐使用uv作为包管理器。uv是一个用Rust编写的高性能Python包和项目管理工具，它不仅能替代pip、pip-tools、pipx、poetry、pyenv、twine和virtualenv等多个工具，还能提供10-100倍的性能提升。作为一个poetry的长期用户，决定趁着这次学习MCP的机会，将个人Python开发环境从poetry迁移到uv。

安装

macOS和Linux用户可以直接使用官方的安装脚本：

# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh

看了一下官方脚本中也是基于Rust的cargo安装。因为我本地有Rust的开发环境，所以直接使用了cargo安装。

cargo install --git https://github.com/astral-sh/uv uv

uv 可通过 Cargo 获取，但由于其依赖于未发布的 crate，必须从 Git 而不是 crates.io 构建。

此外，uv的GitHub 发布页面还提供了适用于不同系统架构的预编译uv二进制文件。

使用Cargo安装的uv，会在~/.cargo/bin/目录下安装uv和uvx两个可执行文件。

uv不仅可以帮助我们管理Python版本，还提供了多种工具tools。安装完uv后，可以使用以下两个命令查看uv的Python和tools的存储目录。

关于工具

许多Python包提供了可以作为工具使用的命令行工具。uv专门支持轻松调用和安装工具。

uv python dir
～/.local/share/uv/python

uv tool dir
～/.local/share/uv/tools

macOS上也可通过homebrew安装uv

uv的基本使用

安装python

查看可用的python版本:

uv python list

安装python:

uv python install 3.13

安装成功后，可以使用uv python list查看。

管理项目

uv支持管理Python项目，这些项目在pyproject.toml文件中定义了它们的依赖项。

创建新项目

使用 uv init 命令可以快速创建一个新的 Python 项目：

uv init hello-world
cd hello-world

要指定具体的python版本，可以使用uv init -p 3.13 hello-world来创建项目。

也可以在当前工作目录下初始化项目：

mkdir hello-world
cd hello-world
uv init

执行后，uv 会自动创建以下项目结构：

.
├── .python-version    # Python版本配置文件
├── README.md         # 项目说明文档
├── main.py          # 主程序文件
└── pyproject.toml   # 项目依赖配置文件

其中 main.py 包含了一个简单的 “Hello world” 程序。你可以使用 uv run 命令来运行它：

uv run main.py

项目结构

一个uv项目由多个文件和目录组成，它们协同工作以允许uv管理项目。除了uv init创建的文件外，当第一次运行项目命令（如uv run、uv sync或uv lock）时，uv还会在项目根目录中创建虚拟环境和uv.lock文件。

完整的项目结构如下：

.
├── .venv
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock

各个文件和目录的作用：

pyproject.toml
pyproject.toml包含项目的元数据：
```
[project]
name = "hello-world"
version = "0.1.0"
description = "添加你的项目描述"
readme = "README.md"
dependencies = []
```
可以使用这个文件指定依赖项，以及项目的描述等详细信息。可以手动编辑此文件，或使用uv add和uv remove命令从终端管理项目。
可以在pyproject.toml的[tool.uv]部分指定uv的配置选项。
.python-version
.python-version文件包含项目的默认Python版本。此文件告诉uv在创建项目的虚拟环境时使用哪个Python版本。
.venv
.venv目录包含项目的Python虚拟环境，uv会在这里安装项目的依赖项。
uv.lock
uv.lock是一个跨平台的锁定文件，包含有关项目依赖项的精确信息。与用于指定项目广泛要求的pyproject.toml不同，锁定文件包含在项目环境中安装的精确解析版本。这个文件应该被纳入版本控制，以允许在不同机器上进行一致且可重现的安装。
尽管uv.lock是一个可读的TOML文件，但它由uv管理，不应手动编辑。

管理依赖

可以使用 uv add 命令向pyproject.toml添加依赖项。这个命令会同时更新uv.lock和虚拟环境：

uv add requests

要移除一个包，可以使用 uv remove 命令：

uv remove requests

要升级一个包，可以使用带 --upgrade-package参数的uv lock命令：

uv lock --upgrade-package requests

--upgrade-package 参数会尝试将指定的包更新到最新的兼容版本，同时保持锁文件中其他依赖项不变。

pypi源配置

默认情况下，uv使用PyPI进行依赖解析和包安装。可以通过 pyproject.toml 文件中的 [[tool.uv.index]] 配置选项（或命令行参数 --index）来使用其他包索引源，包括私有源。

这对于需要使用公司内部私有包仓库或者国内镜像源的用户来说非常实用。

[[tool.uv.index]]
name = "private-pypi"
url = "https://mirrors.aliyun.com/pypi/simple/"
# url = "https://pypi.example.com/repository/pypi-public/simple"
default = true

如果指定的pypi是私有仓库，并且开启了认证，可以使用下面的方法为私有pypi指定用户名和密码。通过设置~/.netrc文件，设置这个文件同时对poetry和pip有效。

vi ~/.netrc
machine pypi.example.com
login theuser
password changeme

chown $USER ~/.netrc
chmod 0600 ~/.netrc

还可以通过环境变量的方式，其中INDEX_PRIVATE是配置文件中索引名称的大写版本，非字母数字字符被替换为下划线：

export UV_INDEX_PRIVATE_PYPI_USERNAME=username
export UV_INDEX_PRIVATE_PYPI_PASSWORD=password

注意.netrc配置文件的优先级高于环境变量。

打包

uv build

ls dist                                                                       
hello-0.1.0-py3-none-any.whl  hello-0.1.0.tar.gz

.whl文件是Python的Wheel格式安装包。可在虚拟环境中使用pip本地安装: pip install hello-0.1.0-py3-none-any.whl。

参考

https://docs.astral.sh/uv/