macOS 安装 Python

macOS 自带的 Python 是由 Apple 为系统工具提供的旧版本（通常是 Python 3.9 左右），既不适合开发，也不能随意升级。本节将介绍在 macOS 上通过官方安装程序、Homebrew、pyenv 与 uv 安装 Python 的完整流程，并配置好 pip 与 venv（虚拟环境，Virtual Environment）。

前置知识

阅读本节前，建议先了解：Python 是什么

基础概念

macOS 基于 Unix，终端（Terminal）基于 zsh（macOS Catalina 起的默认 Shell）。因此 macOS 上的 Python 安装与 Linux 有许多共通之处，但又有 Apple 特定的限制。

几个关键概念：

概念	说明
System Python	/usr/bin/python3，Apple 提供的系统 Python，不要修改
Homebrew	macOS 上最流行的包管理器（Package Manager）
Framework Build	macOS 特有的 .framework 结构，支持 GUI 与 IDLE
Formula	Homebrew 的包定义，如 python@3.12
Keg	Homebrew 安装单个包的目录，如 /opt/homebrew/Cellar/python@3.12
zsh 配置文件	~/.zshrc（登录 Shell）与 ~/.zprofile

永远不要修改系统 Python

/usr/bin/python3 是 Apple 用于系统脚本的解释器，直接 pip install 到系统环境或替换它可能导致系统工具异常。请始终安装独立的 Python。

语法与用法

macOS 推荐使用 Homebrew 安装：

# 安装 Homebrew（若尚未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Python 3.12
brew install python@3.12

# 安装 Python 3.13
brew install python@3.13

# 查看 Homebrew 安装信息
brew info python@3.12

使用 pyenv 管理多版本：

# 安装 pyenv
brew install pyenv

# 安装指定版本
pyenv install 3.12.7

# 设置全局版本
pyenv global 3.12.7

# 查看版本
python --version

详细说明

方式一：官方安装程序

官方安装程序提供标准的 framework 构建，适合需要 IDLE 图形界面或与 GUI 框架（如 Tkinter）配合的用户。

1. 访问 python.org/downloads/macos。
2. 下载最新的 macOS 64-bit universal2 installer，例如 python-3.12.7-macos11.pkg。
3. 双击 .pkg 文件，按向导完成安装。
4. 安装程序会自动把 python3 符号链接（Symbolic Link）放到 /usr/local/bin。

# 验证安装
python3 --version
# 输出：Python 3.12.7

# 查看安装路径
which python3
# 输出：/usr/local/bin/python3     （Intel Mac）
# 或 /Library/Frameworks/Python.framework/Versions/3.12/bin/python3

官方安装程序会把可执行文件放在：

/Library/Frameworks/Python.framework/Versions/3.12/bin/
├── python3
├── pip3
├── idle3
└── ...

关于 python.org 与 universal2

universal2 表示同时包含 arm64（Apple Silicon）与 x86_64（Intel）两种架构，可在两类 Mac 上原生运行。

方式二：Homebrew（推荐）

Homebrew 是 macOS 上最推荐的安装方式，安装位置依架构而异：

架构	Homebrew 前缀	二进制目录
Apple Silicon (M 系列)	/opt/homebrew	/opt/homebrew/bin
Intel	/usr/local	/usr/local/bin

# 安装 Python 3.12
brew install python@3.12

# Homebrew 默认不会覆盖 /usr/bin/python3，需要手动使用版本化命令
python3.12 --version
which python3.12
# 输出：/opt/homebrew/bin/python3.12

# 或者把 python3 指向 Homebrew 版本（通过 PATH 优先级）
export PATH="/opt/homebrew/opt/python@3.12/libexec/bin:$PATH"

# 验证
python3 --version
python --version   # 该路径下同时提供 python

libexec/bin 的作用

/opt/homebrew/opt/python@3.12/libexec/bin 目录中包含 python、pip 及 pip3（已正确指向当前版本），将其置于 PATH 前部可让 python 与 pip 直接可用，而不影响 Homebrew 对其他包的管理。

方式三：pyenv（多版本管理）

pyenv 是 macOS 与 Linux 上最常用的 Python 版本管理器，可精确切换版本。

# 1. 安装 pyenv
brew install pyenv

# 2. 在 ~/.zshrc 中添加初始化脚本
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

# 3. 重新加载配置
source ~/.zshrc

# 4. 查看可安装版本
pyenv install --list | grep " 3\.12"

# 5. 安装指定版本
pyenv install 3.12.7

# 6. 设为全局默认
pyenv global 3.12.7

# 7. 验证
python --version
pyenv versions

在项目目录中设置局部版本：

# 进入项目目录
cd ~/projects/demo

# 设置该项目使用 3.11.9
pyenv local 3.11.9

# 会在项目根目录生成 .python-version 文件
cat .python-version
# 输出：3.11.9

方式四：uv（新一代极速工具链）

uv 是用 Rust 编写的极速 Python 包与版本管理工具，可同时管理 Python 版本与依赖。

# 安装 uv
brew install uv

# 或使用官方脚本
curl -LsSf https://astral.sh/uv/install.sh | sh

# 使用 uv 安装 Python
uv python install 3.12

# 列出已管理的 Python
uv python list

# 固定项目使用的 Python 版本
uv python pin 3.12.7

uv 的优势

uv 解析与安装依赖的速度通常比 pip 快 10~100 倍，并内置虚拟环境创建、锁定文件（uv.lock）与 Python 版本管理，是近年社区力推的现代工具链。详见 uv 工具链管理。

环境变量配置

zsh 路径配置

# 编辑 ~/.zshrc
nano ~/.zshrc

# 将 Homebrew Python 的 bin 目录加入 PATH（放在最前面以优先使用）
export PATH="/opt/homebrew/opt/python@3.12/libexec/bin:$PATH"

# 保存后重新加载
source ~/.zshrc

# 验证 PATH 是否生效
echo $PATH | tr ':' '\n' | head -5

常用 Python 环境变量

# 在 ~/.zshrc 中添加
# 强制 UTF-8 模式
export PYTHONUTF8=1

# 不生成 .pyc 缓存文件
export PYTHONDONTWRITEBYTECODE=1

# 追加模块搜索路径
export PYTHONPATH="$HOME/pylibs"

# pip 配置国内镜像（可选）
export PIP_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"

也可以写入 pip 配置文件 ~/.config/pip/pip.conf：

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
timeout = 60

验证安装

基本验证命令

# 1. 版本
python3 --version
# 或（使用 Homebrew libexec 后）
python --version

# 2. pip
python3 -m pip --version

# 3. 解释器路径（确认不是 /usr/bin/python3）
python3 -c "import sys; print(sys.executable)"

# 4. 架构信息（确认 arm64 或 x86_64）
python3 -c "import platform; print(platform.machine(), platform.architecture())"

# 5. site-packages 位置
python3 -c "import site; print(site.getsitepackages())"

检查是否为系统 Python

# 系统 Python 路径特征
python3 -c "import sys; print(sys.prefix)"
# 若输出 /System/Library/Frameworks/Python.framework/... 则说明在使用系统 Python

# 推荐输出
# /opt/homebrew/opt/python@3.12/Frameworks/Python.framework/Versions/3.12
# 或 ~/.pyenv/versions/3.12.7

环境自检脚本

"""env_check.py —— 检查当前 Python 环境，避免误用系统 Python。"""

import sys
from pathlib import Path


def main() -> None:
    """打印环境关键信息，并对系统 Python 给出警告。"""
    prefix: str = sys.prefix
    print(f"Python 版本：{sys.version.split()[0]}")
    print(f"解释器路径：{sys.executable}")
    print(f"环境前缀：{prefix}")

    # 判断是否误用 Apple 系统 Python
    if prefix.startswith("/System/Library"):
        print("⚠️  警告：当前正在使用 macOS 系统 Python，不建议用于开发！")
    else:
        print("✅ 当前为独立安装的 Python，可放心使用。")

    print(f"包搜索路径数量：{len(sys.path)}")
    print(f"用户站点目录：{Path.home() / 'Library/Python'}")


if __name__ == "__main__":
    main()

python3 env_check.py

实战示例

案例一：从零搭建 Homebrew + venv 开发环境

# 1. 确认 Homebrew 可用
brew --version

# 2. 安装 Python 3.12
brew install python@3.12

# 3. 加入 PATH（Apple Silicon）
echo 'export PATH="/opt/homebrew/opt/python@3.12/libexec/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 4. 验证
python --version

# 5. 创建项目
mkdir -p ~/projects/demo && cd ~/projects/demo

# 6. 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate

# 7. 升级 pip、安装依赖
python -m pip install --upgrade pip
pip install requests rich

# 8. 保存依赖
pip freeze > requirements.txt

# 9. 退出
deactivate

案例二：pyenv 管理多版本并切换

# 安装两个版本
pyenv install 3.11.9
pyenv install 3.12.7

# 设置全局默认
pyenv global 3.12.7

# 在特定项目中使用 3.11.9
cd ~/projects/legacy
pyenv local 3.11.9

# 查看当前生效版本
pyenv version
# 输出：3.11.9 (set by /Users/<用户名>/projects/legacy/.python-version)

# 创建该项目的虚拟环境
python -m venv .venv
source .venv/bin/activate
python --version
# 输出：Python 3.11.9

pyenv 与虚拟环境的配合

pyenv 管理的是解释器版本，venv 管理的是项目依赖。两者结合使用是最佳实践：用 pyenv 切换解释器版本，再用 venv 隔离项目依赖。

案例三：使用 uv 极速创建项目

# 安装 uv
brew install uv

# 创建新项目（自动创建虚拟环境与 pyproject.toml）
uv init my-project
cd my-project

# 固定 Python 版本
uv python pin 3.12.7

# 添加依赖（自动写入 pyproject.toml 与 uv.lock）
uv add requests

# 运行脚本
uv run python main.py

注意事项

• 不要用 sudo pip：会污染系统 Python，且可能破坏系统工具。
• 系统 Python 只读：/usr/bin/python3 由 SIP（System Integrity Protection）保护，无法修改。
• PATH 优先级：/opt/homebrew/bin 需在 /usr/bin 之前，否则 python3 会命中系统版本。
• .pkg 与 Homebrew 冲突：同时通过两种方式安装可能导致 python3 混乱，建议只保留一种。
• zsh 与 bash 配置不同：macOS 默认 zsh，配置写入 ~/.zshrc 而非 ~/.bashrc。
• Xcode Command Line Tools：编译部分 C 扩展需要它，可用 xcode-select --install 安装。

常见问题排查表：

现象	原因	解决
python 提示 command not found	Homebrew 只提供 python3	加入 libexec/bin 到 PATH
python 版本是 3.9	命中系统 Python	检查 PATH 优先级与 sys.prefix
pip 安装权限报错	使用了系统 Python	改用独立 Python 或加 --user
ARM Mac 上安装失败	依赖了 x86 版本	使用 arm64 版 Homebrew
zsh: command not found: brew	Homebrew 未加入 PATH	按安装提示追加 shellenv

最佳实践

• 优先 Homebrew 或 pyenv：Homebrew 适合单一稳定版本，pyenv 适合多版本切换。
• 每个项目独立虚拟环境：使用 python -m venv .venv，并将 .venv/ 加入 .gitignore。
• 不要修改系统 Python：始终安装独立版本。
• 配置国内镜像源：加速 pip 安装。
• 统一项目 Python 版本声明：使用 .python-version（pyenv）或 pyproject.toml 的 requires-python。
• 定期 brew upgrade：保持 Python 与依赖为最新安全版本。
• Apple Silicon 用户注意架构一致性：确保 Python、虚拟环境、编译工具均为 arm64，避免通过 Rosetta 混用。

下一节

继续学习：Linux 安装 Python

参考链接

• Python 官方文档 - 在 macOS 上使用 Python
• Python 官方下载页 - macOS
• Homebrew 官方网站
• pyenv 官方仓库
• uv 官方文档
• Python 官方文档 - venv 虚拟环境