使用 uv 来管理 Python 之 uv 使用配置教程

我发现使用 uv 来管理 Python 的版本很方便，且下载依赖之类的操作也很快，整理下面这份详细的 uv 使用配置教程，适合作为以后新建 Python 项目时的参考文档。

---

1. uv 简介

uv 是一款用 Rust 编写的极快速 Python 包管理器和项目管理工具，目标是成为“Python 的 Cargo”。
官网: https://docs.astral.sh/uv/

uv

它能够替代传统的 pip、pip-tools 和 virtualenv 命令，并且在安装、解析依赖和创建虚拟环境等方面有着显著的性能优势，如上图（比 pip 快 10 ～ 100 倍）。此外，uv 还提供了全局缓存机制，既节省磁盘空间，也加速了后续操作。

---

2. 安装 uv

在 macOS 上安装 uv 非常简单，有多种方式可供选择：

2.1 使用 Homebrew 安装

如果已经安装了 Homebrew，可以直接执行：

brew install uv

2.2 使用官方安装脚本

通过 curl 下载并执行安装脚本：

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

2.3 通过 pip 安装

如果更习惯 pip，也可以：

pip install uv

2.4 手动安装

我一开始使用的是

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

来安装的，但是下载失败了，不能忍，我直接到 uv 的 github 仓库的 release 中下载对应版本：https://github.com/astral-sh/uv/releases

因为我还在用 Intel 芯片的 Mac，所以我下载的是：uv-x86_64-apple-darwin.tar.gz

下载完成之后，解压，在 uv 的可执行文件路径下执行：

./uv --version

好家伙，网上下载的不让打开：Apple 无法验证“uv”是否包含可能危害 Mac 安全或泄漏隐私的恶意软件。

直接运行以下命令移除文件的隔离属性：

xattr -d com.apple.quarantine uv

然后把 uv 移动到系统 PATH 中

sudo mv uv /usr/local/bin/uv

安装完成后，可以通过以下命令检查 uv 是否安装成功：

uv -h 或者 uv --version

---

3. 初始化项目

uv 提供了类似于其他现代包管理器的项目初始化命令，可以快速为的 Python 项目生成基础结构。

3.1 创建新项目

进入希望创建项目的目录，执行：

uv init myproject

此命令会在 myproject 目录下生成如下文件：

• pyproject.toml：项目的基本元数据（名称、版本、描述、支持的 Python 版本等）。
• uv.lock：自动生成的锁文件，用于记录所有依赖的具体版本。
• 其他示例文件（如 hello.py 和 README.md），可以根据需要修改或删除。

3.2 查看生成的文件

进入项目目录后，可以使用 ls 命令查看项目结构：

cd myproject
ls

将看到类似下面的输出：

.venv
.gitignore
.python-version
hello.py
pyproject.toml
README.md
uv.lock

---

4. 虚拟环境管理

uv 内置了虚拟环境管理功能，让可以轻松创建、切换和管理项目的虚拟环境。

4.1 创建虚拟环境

在项目根目录下，执行：

uv venv

uv 会自动检测当前项目所需的 Python 版本（依据 pyproject.toml 中的 requires-python），并在项目目录下创建一个名为 .venv 的虚拟环境。

4.2 指定 Python 版本

如果需要使用特定版本的 Python，可以使用 --python 参数：

uv venv --python /usr/local/bin/python3.8

这样会基于指定的 Python 解释器创建虚拟环境。

也可以使用下面的命令来创建指定版本的虚拟环境：

uv venv --python 3.11

4.3 激活虚拟环境

激活虚拟环境（macOS 或 Linux）：

source .venv/bin/activate

完成后，命令行前缀会显示虚拟环境名称，表示当前已经进入该环境。

---

5. 依赖管理

uv 提供了简单直观的命令来添加、更新和删除依赖。

5.1 添加依赖

添加依赖与 npm 或 Cargo 类似，直接执行：

uv add pandas

此命令会：

• 解析并下载 pandas 及其依赖包；
• 更新 pyproject.toml 中的依赖声明；
• 将详细依赖信息写入 uv.lock。

5.2 删除依赖

如果不再需要某个包，可以执行：

uv remove pandas

uv 会自动卸载 pandas 及其不再需要的依赖，同时更新锁文件。

5.3 更新依赖

如果需要升级某个依赖到最新版本，可使用：

uv add --upgrade requests

这会更新 requests 包及其版本号，并同步到虚拟环境中。

---

6. 区分开发与生产环境依赖

uv 支持将依赖分组管理，以便区分开发（dev）和生产（production）环境的依赖。

6.1 添加分组依赖

例如，将 pandas 添加为开发依赖：

uv add --group dev pandas

将 requests 添加为生产依赖：

uv add --group production requests

6.2 查看 pyproject.toml

执行上述命令后，的 pyproject.toml 会自动生成类似下面的结构：

[project]
name = "myproject"
version = "0.1.0"
description = "Add your description here"
requires-python = ">=3.12"
dependencies = []

[dependency-groups]
dev = [
    "pandas>=2.2.3",
]
production = [
    "requests>=2.32.3",
]

这样可以方便在不同场景下安装相应的依赖。

---

7. 运行项目和脚本

uv 除了管理依赖，还集成了运行命令，让无需离开 uv 的管理体系即可运行代码。

7.1 运行项目中的脚本

假设 hello.py 内容如下：

def main():
    print("Hello from myproject!")

if __name__ == "__main__":
    main()

使用 uv 运行：

uv run hello.py

7.2 使用 uv 运行带依赖的脚本

如果脚本中引用了已安装的依赖（如 pandas），确保依赖已添加，然后运行：

uv run hello.py

uv 会自动在项目的虚拟环境中执行代码。

---

8. 高级功能

除了基本的项目初始化、虚拟环境和依赖管理外，uv 还支持以下高级功能：

8.1 脚本依赖管理

如果有单文件脚本，并希望为该脚本单独添加依赖，可以执行：

uv add --script example.py requests

此命令会在脚本内嵌入依赖声明，然后在隔离环境中运行脚本时自动安装相应依赖。

8.2 多版本 Python 管理

uv 可以管理多个 Python 版本，帮助快速切换或安装不同版本的 Python：

uv python install 3.10 3.11 3.12

安装完成后，可以通过：

uv python pin 3.11

将项目固定使用某个 Python 版本。

9 其他

我在尝试安装 browser-use webui 的时候涉及到 uv 的使用，以下是项目地址：
browser-use webui