macOS 上的 Python（CPython）：官方安装器、free-threaded 构建与开发实践全指南

本文基于 CPython 仓库中的官方文档 Doc/using/mac.rst（即《Using Python on a macOS》）整理并扩充而成。macOS 上的 Python 与其他 Unix 平台非常相似，但在安装方式与个别功能上存在差异。本文面向想在 Mac 上快速上手 CPython 的开发者，覆盖从 python.org 官方安装器的图形化/命令行安装、脚本运行方式、常见发行渠道对比，到 3.13+ 引入的 free-threaded（无 GIL）构建、GUI 开发、应用分发与 App Store 合规等进阶主题。读完你不仅能顺利装好并运行 Python，还能理解官方安装包在系统内的布局原理，并在需要时用源码级配置实现深度定制。

说明：仓库当前 main 分支版本为 3.16.0a0（见 Include/patchlevel.h）。文档中形如 X.Y、X.Yt 的版本号均为渲染占位符，实际使用时请以你下载安装包的真实版本号替换（下文示例多以 3.15 代指，因为 free-threading 默认安装等特性在 3.15 引入）。

一、从 python.org 获取并安装 Python for macOS

1.1 安装包形态与构建架构

对于当前仍在维护支持的 Python 版本（不属于 security 安全维护状态者），CPython 发布团队会为每个新版本产出一个 Python for macOS 安装器。官方建议尽可能使用最新且受支持的 Python 版本。

当前官方安装器提供的是 universal2 二进制的 Python，可在一个二进制包内同时原生支持 Apple Silicon（arm64） 与 Intel（x86_64） 架构的 Mac，通常兼容 macOS 10.15 Catalina 及以上 系统。下载得到的文件是标准 macOS 安装包（.pkg），每个文件的校验和、大小与 Sigstore 签名等完整性信息都会列在发布下载页；安装包及其内容使用 PSF（Python Software Foundation）的 Apple Developer ID 证书签名并公证（notarized），以满足 macOS Gatekeeper 的要求。

这一架构策略在源码仓库中亦有印证：Mac/BuildScript/README.rst 记录了发布包由 build-installer.py 脚本构建，示例命令为：

/path/to/bootstrap/python3 build-installer.py \
    --universal-archs=universal2 \
    --dep-target=10.9

即构建一个最低部署目标为 macOS 10.9、同时含 arm64 与 x86_64 的 fat binary（源码中还额外构建了 OpenSSL、Tcl/Tk、NCurses、SQLite、XZ、mpdecimal 等第三方库，而 readline、zlib、bz2 则使用系统版本）。

1.2 图形化安装步骤

默认安装只需要双击下载的 .pkg 文件，随后 macOS 标准的安装器应用会引导你完成若干步骤：

1. 介绍页（Introduction）：安装器欢迎界面，点击 Continue 继续。

2. Read Me（自述）：这里会记录将要安装的 Python 版本、支持的 macOS 版本等关键信息，可能需要滚动阅读全文。默认情况下，这份 Read Me 也会被安装到 /Applications/Python X.Y/ 目录下，供日后随时查阅。
3. 许可证（License）：展示 Python 及其余随附软件的许可协议，必须点击 Agree 同意后才能进入下一步。许可证文件同样会被安装到系统内供日后阅读。
4. 安装类型（Installation Type）：绝大多数场景使用默认的标准安装组合即可。

5. 自定安装（Customize）：点击 Customize 按钮可以勾选或取消特定安装组件，点击每个包名可查看其说明。可选组件中有一个默认勾选的 free-threaded 特性包（详见下文“安装 free-threaded 二进制”一节）。

6. 无论是否自定义，点击 Install 即开始安装。此时系统会要求输入一个具备 Administrator（管理员）权限的 macOS 用户名密码，因为安装后的 Python 将对 Mac 的所有用户可用。
7. 安装完成会出现 Summary（摘要） 窗口，随后需要在 /Applications/Python X.Y/ 窗口中双击运行 Install Certificates.command 以完成收尾。
8. 该命令会打开一个临时的 Terminal（终端）窗口，借助刚安装的新 Python 下载并安装其运行所需的 SSL 根证书。当终端中出现 Successfully installed certifi 与 update complete 字样，即表示安装彻底完成，可以关闭终端与安装器窗口。

1.3 默认安装会带来什么

一次默认安装会在系统中放置三部分内容：

• /Applications 下的 Python X.Y 文件夹：内含标准发行版自带的集成开发环境 IDLE，以及负责处理在 Finder 中双击运行 Python 脚本的 Python Launcher；
• 框架目录 /Library/Frameworks/Python.framework：包含 Python 可执行文件与库，安装器会把该位置加入你的 shell PATH；
• /usr/local/bin/ 下的 Python 可执行文件符号链接。

如需卸载 Python，移除上述三部分即可。

1.4 与 Apple 系统自带 Python 的关系

需要特别留意：较新版本的 macOS 会在 /usr/bin/python3 提供一个 python3 命令，它链接到的通常是较旧且不完整的 Python，专供 Apple 开发工具（Xcode 或 Command Line Tools for Xcode）使用。

• 永远不要修改或删除这套系统 Python，它由 Apple 控制，且被 Apple 及第三方软件依赖；
• 从 python.org 另装新版后，机器上会存在两套功能上都能用的 Python，且可共存；
• 官方安装器的默认选项会确保优先使用它安装的 python3 而不是系统的 python3。

二、如何运行 Python 脚本

调用 Python 解释器有两条主要途径。

2.1 在终端中调用

如果你习惯在终端窗口使用 Unix shell，可以调用 python3（或带具体小版本号的 pythonX.Y），并可附上一个或多个命令行选项（完整选项见 Doc/using/cmdline.rst）。运行脚本文件的方式：

python3 myscript.py

若你是新手，可先阅读仓库中的官方教程（见 Doc/tutorial 下交互式使用 Python 的相关章节）熟悉 shell 中交互式使用 Python 的方法。

2.2 通过 IDE 调用

IDLE 是随 Python 标准发行版附带的基础编辑与解释器环境，其 Help 菜单可直接访问 Python 文档，非常适合刚接触 Python 的用户。此外市面上还有大量编辑器与 IDE 可选，仓库中的 Doc/using/editors.rst 有专门整理。

2.3 从 Finder 运行脚本

从 Finder 运行 .py 脚本有两种方式：

• 把脚本文件拖到 Python Launcher 图标上；
• 通过 Finder 的“显示简介（Info）”窗口把 Python Launcher 设为该脚本（或所有 .py 文件）的默认打开应用，然后双击运行。

Python Launcher 提供多种偏好设置来控制脚本的启动方式：按住 Option 拖放可针对单次调用临时修改设置，或通过其 Preferences 菜单做全局修改。

务必注意：直接从 Finder 运行脚本，与在终端中运行结果可能不同——因为前者不在常规的 shell 环境下执行，不会加载 shell profile 中设置的各类环境变量。同时，和运行任何脚本/程序一样，运行前请确认清楚自己在执行什么内容。

三、常见发行版选择（Alternative Distributions）

除 python.org 官方安装器外，macOS 上还存在多个第三方发行渠道，它们可能附带额外功能，例如：

• ActivePython：提供多平台兼容的安装器与文档；
• Anaconda：内置热门科学计算模块（numpy、scipy、pandas 等）与 conda 包管理器；
• Homebrew：macOS 的包管理器，提供多个 Python 版本及大量第三方 Python 包；
• MacPorts：另一款 macOS 包管理器，同样提供多版本 Python，且可能为较旧 macOS 提供预编译版本。

需要注意：这些发行版可能不包含最新版 Python 或其他库，且均不由 CPython 核心团队维护与支持。

四、安装额外的 Python 包

安装第三方包属于“Python 打包”范畴，可参阅 Python 打包用户指南（Python Packaging User Guide）学习最佳实践。仓库源码层面，官方 macOS 安装器已经内置了 pip，直接按标准方式使用即可（涉及 free-threaded 构建时需注意其独立的 pip 实例，见下文）。

五、macOS 上的 GUI 编程

在 Mac 上使用 Python 构建图形界面应用，有几类主流方案：

• tkinter：Python 标准 GUI 工具包，基于跨平台 Tk 工具包，官方安装器中已经随附了 macOS 原生版本的 Tk；
• PyObjC：Python 与 Apple Objective-C/Cocoa 框架的绑定层，可访问近乎完整的 Cocoa API；
• PySide：Qt GUI 工具包的官方 Python 绑定；
• PyQt：Qt 的另一种主流 Python 绑定；
• Kivy：支持桌面与移动平台的跨平台 GUI 工具包；
• Toga：BeeWare 项目的一部分，支持桌面、移动、Web 与命令行应用；
• wxPython：面向桌面操作系统的跨平台工具包。

六、高级主题（一）：安装 free-threaded 二进制

6.1 什么是 free-threaded 构建

Python 3.13 起新增 free-threading 支持（即运行时禁用全局解释器锁 GIL 的构建），并在 3.15 起默认随官方安装器安装。也就是说，当前 python.org 的 macOS 安装包默认会额外安装一个支持 free-threading（以“禁用 GIL”方式运行）的 Python 构建。关于该特性的版本说明可以参看仓库中的发布说明与 Doc/using/configure.rst 中 --disable-gil 相关条目。

free-threaded 模式已可工作并持续改进中，但需要了解：

• 相比常规构建，单线程工作负载存在额外开销；
• 第三方包，尤其是带扩展模块（extension module） 的包，可能尚未准备好适配 free-threaded 构建——这类模块会重新启用 GIL，从而退回传统行为。

6.2 安装与文件布局

从 3.15 起，free-threading 支持默认安装，它被封装为独立安装选项，可通过上文提到的“安装类型”步骤中的 Customize 按钮取消勾选。若 Free-threaded Python 包名前方的勾选框保持选中（默认），安装器会在 /Library/Frameworks 中额外安装一个 PythonT.framework，与常规的 Python.framework 并存。这样的布局让你可以无冲突地同时保留传统（仅 GIL）构建与 free-threaded 构建，便于安装或测试（此布局未来版本可能调整）。

对应地，free-threaded 解释器的可执行文件名带 t 后缀，例如 python3.15t；其配套的配置工具名为 python3.15t-config，对打包构建者（package builders）较为有用。

6.3 已知注意事项与限制

围绕 free-threaded 包，官方文档列出了一系列实用注意事项：

1. 命令行链接：默认选中的 UNIX command-line tools 包会在 /usr/local/bin 为 pythonX.Yt（free-threaded 解释器）及其配置工具 pythonX.Yt-config 安装链接。由于 /usr/local/bin 通常已在 shell PATH 中，多数情况下无需改动 PATH 即可直接使用 pythonX.Yt。
2. 不支持项：当前版本的 Shell profile updater 包及 /Applications/Python X.Y/ 下的 Update Shell Profile.command 不支持 free-threaded 包。
3. site-packages 相互独立：free-threaded 构建与传统构建拥有独立的搜索路径和独立的 site-packages 目录。默认情况下，若某个包需要在两种构建中同时可用，就得分别安装一次。free-threaded 包会为 pythonX.Yt 安装独立的 pip 实例：

   # 不借助 venv 时用 pip 安装包
   python3.15t -m pip install <package_name>
   

4. 推荐使用虚拟环境：同时面对多个 Python 环境时，最稳妥的方式是创建并使用虚拟环境（venv），以避免命令名冲突及“当前到底在用哪个 Python”的困惑：

   python3.15t -m venv <venv_name>
   

   然后按常规方式 activate 该环境。
5. 运行 free-threaded 版 IDLE：

   python3.15t -m idlelib
   

6. 环境变量共享：两种构建的解释器响应相同的 PYTHON* 环境变量（参见 Doc/using/cmdline.rst 的环境变量一节），例如若 shell profile 中设置了 PYTHONPATH，可能产生意想不到的结果。必要时可使用类似 -E 的命令行选项（见 Doc/using/cmdline.rst 接口选项一节）忽略这些环境变量。
7. 共享第三方动态库：free-threaded 构建会链接传统框架中安装的第三方共享库（如 OpenSSL、Tk）。这也意味着两种构建共享由 Install Certificates.command 安装的同一套信任证书，因此该命令只需运行一次。
8. PATH 的显式管理：如果你不能依赖 /usr/local/bin 中指向 python.org free-threaded pythonX.Yt 的链接（例如你在该位置装了自建版本，或它被其他发行版占用），可以显式把 PythonT 框架的 bin 目录加入 shell PATH：

   export PATH="/Library/Frameworks/PythonT.framework/Versions/3.15/bin":"$PATH"
   

   传统框架的默认安装行为类似（只是换成 Python.framework）。需要注意：当两个框架的 bin 目录同时在 PATH 中、且存在同名命令（如两个 python3.15）时，究竟启用哪个取决于它们在 PATH 中的先后顺序，可用 which python3.x / which python3.xt 查看实际解析路径。虚拟环境有助于消除这类歧义；另一种做法是给目标解释器建立 shell 别名：

   alias py3.15="/Library/Frameworks/Python.framework/Versions/3.15/bin/python3.15"
   alias py3.15t="/Library/Frameworks/PythonT.framework/Versions/3.15/bin/python3.15t"
   

七、高级主题（二）：用命令行自动化安装

若希望把安装流程自动化（而非依赖图形化 Installer 应用），可以使用 macOS 命令行工具 installer。它也支持选择非默认选项，不过命令本身较为晦涩（详见 man installer）。下面以示例版本 3.15.0b2 的 release 包、并取消勾选 free-threaded 解释器选项为例，给出一个完整 shell 片段：

RELEASE="python-3.15.0b2-macos11.pkg"

# 下载安装包
curl -O https://www.python.org/ftp/python/3.15.0/${RELEASE}

# 创建 choicechanges 以定制安装：
#   关闭 org.python.Python.PythonTFramework-3.15 包
#   其余组件保持默认（全部安装）
cat > ./choicechanges.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<array>
        <dict>
                <key>attributeSetting</key>
                <integer>0</integer>
                <key>choiceAttribute</key>
                <string>selected</string>
                <key>choiceIdentifier</key>
                <string>org.python.Python.PythonTFramework-3.15</string>
        </dict>
</array>
</plist>
EOF

sudo installer -pkg ./${RELEASE} -applyChoiceChangesXML ./choicechanges.plist -target /

其中 choicechanges.plist 把 org.python.Python.PythonTFramework-3.15 这个安装项的 selected 属性置为 0（不选），其余保持默认。从源码看，对应包标识符体现了前面讲过的“默认额外安装 PythonT.framework”这一布局。

安装完成后，可以这样验证两套构建都可正常使用（假设启用了 Unix Command Tools 包）：

$ # 验证 free-threaded 解释器是否安装
$ /usr/local/bin/python3.15t -VV
Python 3.15.0b2 free-threading build (v3.15.0b2:3a83b172af, Jun  5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]
$ # 验证传统解释器
$ /usr/local/bin/python3.15 -VV
Python 3.15.0b2 (v3.15.0b2:3a83b172af, Jun  5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
$ # 若 /usr/local/bin 在 $PATH 中，不带前缀也能直接调用
$ python3.15t -VV
Python 3.15.0b2 free-threading build (v3.15.0b2:3a83b172af, Jun  5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]
$ python3.15 -VV
Python 3.15.0b2 (v3.15.0b2:3a83b172af, Jun  5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]

-VV 输出中带 free-threading build 字样即可区分 free-threaded 与传统构建。

限制提醒：当前 python.org 安装器只安装到固定位置（/Library/Frameworks/、/Applications、/usr/local/bin），无法通过 installer 的 -domain 选项安装到其他位置。

八、高级主题（三）：分发 Python 应用与 App Store 合规

8.1 打包成独立应用

把 Python 代码转换成可独立分发的应用，社区里有多种成熟工具：

• py2app：专门用于把 Python 项目打包成 macOS 的 .app bundle；
• Briefcase：BeeWare 项目的一部分，跨平台打包工具，在 macOS 上可生成 .app，并协助处理签名与公证（signing & notarization）；
• PyInstaller：跨平台打包工具，可产出单文件或单目录形式的可分发产物。

8.2 让应用通过 App Store 审核

提交到 macOS App Store 分发的应用必须通过 Apple 的应用审核流程，其中包含一组自动化校验规则，会检查提交的应用 bundle 中是否存在“问题代码”。

Python 标准库中存在少量已知会触发这些自动化规则的代码。虽然这些违规看起来属于误报（false positives），但 Apple 的审核规则无法申诉，因此要让应用通过审核，就必须对 Python 标准库做相应修改。

为此，CPython 源码仓库中准备了补丁文件 Mac/Resources/app-store-compliance.patch，会移除所有已知会在 App Store 审核中引发问题的代码。例如从补丁内容可以看到，它会从 Lib/urllib/parse.py 的 URL scheme 白名单中删除 itms-services（并同步调整对应测试），因为该 scheme 与 App Store 审核规则冲突。

该补丁在 CPython 以 --with-app-store-compliance 选项配置构建时自动应用。其定义位于 configure.ac（第 734 行起）：默认值 yes 时，在 Darwin/iOS 系统上自动指定 Mac/Resources/app-store-compliance.patch（iOS 与 macOS 可共用该补丁），其余系统会直接报错提示没有可用的默认补丁；你也可以通过 --with-app-store-compliance=PATCH-FILE 显式传入自定义补丁文件。

需要强调的是：正常情况下在 Mac 上使用 CPython 并不需要这个补丁；在 macOS App Store 之外分发应用也不需要。它仅在以 macOS App Store 作为分发渠道时才必须使用。

九、更多资源

官方 Help 页面汇集了大量实用资源链接；Pythonmac-SIG 邮件列表则是专门面向 Mac 上 Python 用户与开发者的另一支持渠道。仓库内 Doc/using 目录还收录了面向 Unix、Windows、Android 与 iOS 平台的同类指南，可作对照阅读。