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

📅 2025-03-26 | 🖱️

最近在开发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用户可以直接使用官方的安装脚本：

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

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

1cargo 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专门支持轻松调用和安装工具。

1uv python dir
2～/.local/share/uv/python
3
4uv tool dir
5～/.local/share/uv/tools

uv的基本使用 #

安装python #

查看可用的python版本:

1uv python list

安装python:

1uv python install 3.13

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

管理项目 #

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

创建新项目

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

1uv init hello-world
2cd hello-world

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

1mkdir hello-world
2cd hello-world
3uv init

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

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

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

1uv run main.py

项目结构 #

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

完整的项目结构如下：

 1.
 2├── .venv
 3│   ├── bin
 4│   ├── lib
 5│   └── pyvenv.cfg
 6├── .python-version
 7├── README.md
 8├── main.py
 9├── pyproject.toml
10└── uv.lock

各个文件和目录的作用：

1. pyproject.toml

   pyproject.toml包含项目的元数据：

   1[project]
   2name = "hello-world"
   3version = "0.1.0"
   4description = "添加你的项目描述"
   5readme = "README.md"
   6dependencies = []
   

   可以使用这个文件指定依赖项，以及项目的描述等详细信息。可以手动编辑此文件，或使用uv add和uv remove命令从终端管理项目。

   可以在pyproject.toml的[tool.uv]部分指定uv的配置选项。

2. .python-version

   .python-version文件包含项目的默认Python版本。此文件告诉uv在创建项目的虚拟环境时使用哪个Python版本。

3. .venv

   .venv目录包含项目的Python虚拟环境，uv会在这里安装项目的依赖项。

4. uv.lock

   uv.lock是一个跨平台的锁定文件，包含有关项目依赖项的精确信息。与用于指定项目广泛要求的pyproject.toml不同，锁定文件包含在项目环境中安装的精确解析版本。这个文件应该被纳入版本控制，以允许在不同机器上进行一致且可重现的安装。

   尽管uv.lock是一个可读的TOML文件，但它由uv管理，不应手动编辑。

管理依赖 #

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

1uv add requests

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

1uv remove requests

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

1uv lock --upgrade-package requests

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

pypi源配置 #

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

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

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

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

1vi ~/.netrc
2machine pypi.example.com
3login theuser
4password changeme
5
6chown $USER ~/.netrc
7chmod 0600 ~/.netrc

打包 #

1uv build
2
3ls dist                                                                       
4hello-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/