如何在 Mac 上安装及使用 uv 包管理工具?
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
三个部分很重要:
curl会下载安装脚本。-LsSf让下载过程保持安静,但出错时仍会显示错误信息。- 结尾的
| 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
- 第一个命令会把 Python 3.12.10 下载到你的电脑。这只需做一次,其他项目之后可以重复使用这个 Python 版本。
- 第二个命令告诉这个文件夹使用 Python 3.12.10,并把这个选择保存在名为
.python-version的小文件中。之后任何人——或任何程序——打开这个文件夹,都会使用同一个版本。
步骤 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
右上角的三角形按钮。