如何在 Mac 上安装及使用 uv 包管理工具?

林邦源 · AI 笔记 · 2026年11月1日 · 阅读时间约 5 分钟

English 繁體中文 简体中文

uv 是一个同时管理 Python 版本与项目环境的工具,在 Mac 和 Windows 上使用相同的命令。 本文将用官方命令在 Mac 上安装 uv,然后验证它能正常运行。

为什么用 uv

uv 取代了好几个你原本要逐一安装的工具,而且速度快得多。详情请参阅我的 〈使用 uv 设置 VS Code + Python 指南〉。本文适用于 Mac; Windows 用户请参阅本文的 Windows 版本。

观看演示视频

在 Google Drive 观看 (无需账户)。

安装命令

打开“终端”(Terminal,按 Cmd + Space,输入 Terminal,然后按回车),粘贴以下命令,再按回车:

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

三个部分很重要:

这个脚本是 uv 的开发公司 Astral 发布的官方脚本。最新说明请见 docs.astral.sh/uv/getting-started/installation。

验证安装

关闭“终端”窗口并重新打开一个——这一步很重要,因为安装程序会在 你的 shell 配置文件中把 uv 加入 PATH,而已打开的窗口看不到这个变更。

请在英文输入法状态下输入下面命令中的两个连字符。如果中文输入法正在使用中,两个连字符 可能会变成不同的字符,导致命令无法运行。

uv --version

预期输出大致如下(你的版本号可能不同):

uv 0.13.6

看到版本号就代表完成了。

Mac 故障排除

如果打开新窗口后 uv --version 仍显示 command not found, 请改用 Homebrew 安装:brew install uv。我的 〈VS Code + Python 设置指南〉有更多关于安装 uv 的说明。

在存放你自己程序的文件夹中使用 uv

步骤 1:在 VS Code 中打开文件夹

选择 File → Open Folder,选取存放 main.py 和 requirements.txt 的文件夹。然后选择 Terminal → New Terminal 打开终端。

步骤 2:为此文件夹选择 Python 版本

依次运行以下两个命令:

uv python install 3.12.10
uv python pin 3.12.10

步骤 3:安装程序所需的软件包——从两个选项中择一

选项 1

uv init
uv add -r requirements.txt

uv init 会创建一个 Python 项目文件 pyproject.toml。TOML 是 Tom's Obvious Minimal Language 的缩写——一种为人类而设的配置文件格式 (toml.io)。这个文件记录了 项目所需的 Python 版本和软件包。

uv add -r requirements.txt 会读取软件包清单,把每个软件包安装到项目的环境中。

选项 2

uv sync

uv sync 会严格按照文件夹中 uv.lock 文件所列的软件包进行安装, 并移除多余的软件包,让你得到与原项目相同的环境。因此它适合你从别人那里下载的文件夹, 例如 GitHub 项目。在选项 2 中,请勿运行 uv init:文件夹中已有 pyproject.toml,uv 不会替换它。

步骤 4:运行程序

uv run main.py

要运行程序时,输入 uv run,后面加上程序的文件名,例如 main.py。

每个文件夹只需做一次步骤 1 至 3。之后再次打开文件夹时,直接运行程序即可。

如果软件包没有变动,你只想修改程序,编辑 main.py 后再次输入 uv run main.py 即可。

我认为一个好习惯是把所有软件包都记录在 requirements.txt 中。新增软件包时, 先编辑 requirements.txt 加入软件包并保存,然后再次输入 uv add -r requirements.txt。无论你在步骤 3 选择了选项 1 还是选项 2, 这个习惯都适用:uv add -r requirements.txt 会更新项目记录并安装新增的 软件包,让一切保持同步。

步骤 5:把 VS Code 指向这个环境

按 Cmd + Shift + P 打开命令面板,输入 Python: Select Interpreter,然后选取 uv 为此文件夹创建的环境。 如果文件夹名称是 folder-ai-hello-world,列表中会出现带有该名称的条目。 选取后,你还有第二种运行程序的方式:在编辑器中打开文件,点击 Visual Studio Code 右上角的三角形按钮。