首页 > 脚本专栏 > python > Mac上配置Python开发环境

在Mac上配置Python开发环境的完整流程

2026-08-19 08:26:52 作者：看风起长林

macOS是基于Unix的系统,和Linux一样天然适合编程开发,Python在这类系统上运行得特别流畅,读完这篇,你不仅会装好Python,还会搞懂Homebrew、pyenv、iTerm2、zsh这些Mac开发者的标配工具,需要的朋友可以参考下

一、开篇：Mac——Python开发的理想平台

如果你用的是Mac，恭喜你。macOS是基于Unix的系统，和Linux一样天然适合编程开发。Python在这类系统上运行得特别流畅，终端（Terminal）的使用体验也远胜于Windows的CMD。

但这不意味着你不需要配置。Mac自带的Python又老又不好用，你需要一套正确的配置方案。这篇文章就是Mac用户的专属深度指南。

读完这篇，你不仅会装好Python，还会搞懂Homebrew、pyenv、iTerm2、zsh这些Mac开发者的标配工具。

二、先看看系统自带了什么

2.1 检查系统Python

打开Terminal（终端），它在 Launchpad → 其他 → 终端，或者按 Command + 空格 搜索"终端"。

# 检查系统自带的Python
which python
# 通常是：/usr/bin/python
python --version
# 可能是：Python 2.7.18（老系统）或 Python 3.x
# 检查python3
which python3
python3 --version

系统自带的Python不要动！不要尝试删除或修改 /usr/bin/python。macOS的一些系统组件依赖于它。我们要做的不是在它上面修修补补，而是安装一套独立的、更新的Python。

2.2 macOS上Python版本的历史遗留问题

从macOS Catalina（10.15）开始，Apple就不再预装Python 2了，但 /usr/bin/python3 指向的可能是一个较旧的Python 3版本（比如3.8或3.9）。而且这个系统Python缺少一些开发常用的配置。

正确做法：用Homebrew安装一套独立的Python，不碰系统的Python。

三、Homebrew：Mac开发者必备的包管理器

3.1 Homebrew是什么

Homebrew是macOS上最流行的包管理器。你可以把它理解为"Mac上的apt-get"或"命令行版的App Store"。它可以帮你安装、更新、卸载各种开发工具。

用Homebrew装Python的好处：

一键安装，自动处理依赖
方便更新：brew upgrade python
干净卸载：brew uninstall python，不会留垃圾文件
安装的Python独立于系统Python，互不干扰

3.2 安装Homebrew

打开Terminal，粘贴以下命令：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装过程中：

会要求输入你的Mac登录密码（输入时不显示，这是正常的）
按回车确认安装Xcode Command Line Tools（如果没装过的话）
等待安装完成（视网速可能需要几分钟）

安装完成后，按照屏幕提示，可能需要运行以下命令将brew添加到PATH：

# Intel芯片的Mac
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"

# Apple Silicon（M1/M2/M3）芯片的Mac
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

验证安装：

brew --version
# 输出类似：Homebrew 4.x.x

3.3 Homebrew常用命令速查

# 搜索一个包
brew search python

# 安装一个包
brew install python@3.12

# 查看已安装的包
brew list

# 查看某个包的信息
brew info python@3.12

# 更新Homebrew自身
brew update

# 升级所有已安装的包
brew upgrade

# 卸载一个包
brew uninstall python@3.12

# 清理旧版本和缓存
brew cleanup

# 检查Homebrew是否有问题
brew doctor

定期运行 brew update && brew upgrade 保持所有工具处于最新状态，是好习惯。

四、用Homebrew安装Python

4.1 安装最新Python

# 安装Python 3.12
brew install python@3.12

# 安装过程中Homebrew会自动处理依赖，安装完成后：
python3 --version
# Python 3.12.x

pip3 --version
# pip 24.x from /opt/homebrew/lib/python3.12/site-packages/pip (python 3.12)

4.2 Python被装到了哪里

# 查看python3的实际路径
which python3
# Apple Silicon: /opt/homebrew/bin/python3
# Intel: /usr/local/bin/python3

# 这是一个符号链接，指向实际的可执行文件
ls -la $(which python3)
# ... -> ../Cellar/python@3.12/3.12.x/bin/python3

Homebrew把Python装在自己的Cellar目录中，然后在 /opt/homebrew/bin/（或 /usr/local/bin/）下创建符号链接。这样做的好处是升级时可以保留旧版本，出问题还能回退。

4.3 安装多个Python版本

# 安装Python 3.12
brew install python@3.12

# 安装Python 3.11
brew install python@3.11

# 安装Python 3.10
brew install python@3.10

# 查看所有已安装的Python版本
ls /opt/homebrew/opt/ | grep python
# python@3.10
# python@3.11
# python@3.12

不同版本的命令是不同的：

python3 --version          # 指向最新安装的版本
python3.12 --version       # 明确调用3.12
python3.11 --version       # 明确调用3.11

五、pyenv：多版本Python管理的终极方案

5.1 为什么需要pyenv

如果你需要在一台Mac上灵活切换多个Python版本，pyenv是最佳选择。它比Homebrew的多版本管理更加灵活。

pyenv的核心能力：

安装任意版本的Python（包括已停止维护的老版本和最新开发版）
全局设置默认Python版本
按项目目录自动切换Python版本
每个项目可以锁定自己的Python版本

5.2 安装pyenv

# 用Homebrew安装pyenv
brew install pyenv

# 配置shell（zsh是macOS的默认shell）
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

# 使配置生效
source ~/.zshrc

5.3 pyenv常用命令

# 查看所有可安装的Python版本
pyenv install --list

# 安装指定版本
pyenv install 3.12.1
pyenv install 3.11.7
pyenv install 3.10.13

# 查看已安装的版本
pyenv versions
#   system          ← 系统自带的Python
#   3.10.13
# * 3.11.7          ← 星号表示当前全局版本
#   3.12.1

# 设置全局默认版本
pyenv global 3.12.1

# 设置当前目录（项目）的Python版本
cd ~/my_project
pyenv local 3.11.7
# 这会在当前目录创建 .python-version 文件

# 查看当前使用的版本
pyenv version

5.4 pyenv的工作原理解析

pyenv不修改系统Python，也不依赖PATH的优先级。它通过一个称为"垫片（shim）"的机制工作：

pyenv在PATH最前面插入 ~/.pyenv/shims/ 目录
当你输入 python 时，实际执行的是shims目录下的一个脚本
这个脚本读取当前目录的 .python-version 或全局配置
然后转发给对应的Python版本

# 查看shim机制
which python
# /Users/你的用户名/.pyenv/shims/python

# 查看当前使用的真正Python路径
pyenv which python
# /Users/你的用户名/.pyenv/versions/3.12.1/bin/python

pyenv让你可以在不同项目间自由切换Python版本，非常优雅。

六、iTerm2与终端环境优化

6.1 iTerm2：终端体验的革命性升级

macOS自带的Terminal.app功能比较基础。iTerm2是Mac上最强大的终端模拟器，免费开源。

iTerm2相比原生Terminal的优势：

分屏显示（Cmd + D 水平分屏，Cmd + Shift + D 垂直分屏）
全局热键呼出/隐藏终端
强大的搜索功能（Cmd + F）
选中即复制，右键即粘贴
丰富的主题和配色方案

安装方式：

# 用Homebrew安装
brew install --cask iterm2

# 或从官网下载：https://iterm2.com

6.2 zsh配置：让命令行更智能

macOS从Catalina开始默认使用zsh作为shell（之前是bash）。配合oh-my-zsh，zsh会非常强大。

# 确认当前shell
echo $SHELL
# /bin/zsh

# 安装oh-my-zsh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

安装完成后，编辑 ~/.zshrc 配置oh-my-zsh的插件：

# 有用的插件
plugins=(
    git                     # git快捷命令
    python                  # python相关别名
    pip                     # pip自动补全
    brew                    # brew自动补全
    zsh-autosuggestions     # 命令自动建议（需要另外安装）
    zsh-syntax-highlighting # 语法高亮（需要另外安装）
)

为Python创建一些便捷别名：

# 在 ~/.zshrc 中添加
alias py='python3'
alias py3='python3'
alias pip='pip3'
alias venv='python3 -m venv'
alias activate='source venv/bin/activate'
alias jn='jupyter notebook'

七、pip在Mac上的特殊注意事项

7.1 pip vs pip3

在Mac上，pip 和 pip3 可能指向不同的Python版本：

# 查看它们的实际路径
which pip
which pip3

# 查看它们关联的Python版本
pip --version
pip3 --version

如果你用Homebrew安装的Python，pip3 通常会正确指向它。如果你用pyenv，pip 会自动指向当前激活的Python版本对应的pip。

养成一个好习惯：不确定的时候用 python3 -m pip 来调用pip，这样保证pip一定属于你当前使用的Python：

python3 -m pip install requests
python3 -m pip list

7.2 Mac上pip安装包的存放位置

# 查看包被装到了哪里
python3 -m pip show requests
# Location: /opt/homebrew/lib/python3.12/site-packages

7.3 Mac特有的SSL证书问题

在某些Mac上运行pip或Python的HTTP请求时，可能遇到SSL证书验证失败：

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED]

这是由于Python自带的证书包和macOS的钥匙串不同步导致的。解决方法：

# 方法1：安装/更新certifi包
pip3 install --upgrade certifi

# 方法2：在Python中手动指定证书路径
# （运行Python安装程序时有个选项可以安装证书）
# 如果你用的是python.org的安装包，安装器最后会弹出
# 一个Install Certificates.command，双击运行它即可

如果用Homebrew安装的Python，通常不会有这个问题。这是直接用python.org安装包时需要注意的。

八、VS Code在Mac上的配置

8.1 安装VS Code

# 用Homebrew安装
brew install --cask visual-studio-code

# 或从官网下载：https://code.visualstudio.com

8.2 Mac版VS Code的特殊设置

# 在终端中打开VS Code（安装code命令）
# 在VS Code中按 Cmd+Shift+P → 输入 "shell command"
# → 选择 "Install 'code' command in PATH"

# 之后你就可以在终端中用code命令打开文件了
code hello.py          # 打开文件
code .                 # 打开当前目录

8.3 Mac版VS Code推荐的Python设置

在VS Code的 settings.json 中（Cmd + Shift + P → Preferences: Open User Settings (JSON)）：

{
    // Python相关设置
    "python.defaultInterpreterPath": "/opt/homebrew/bin/python3",
    "python.terminal.activateEnvironment": true,
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true,
    "python.formatting.provider": "autopep8",
    "python.formatting.autopep8Args": ["--max-line-length=100"],
    // 编辑器通用设置
    "editor.rulers": [100],
    "editor.renderWhitespace": "boundary",
    "files.autoSave": "afterDelay",
    "files.autoSaveDelay": 1000,
    // 终端设置
    "terminal.integrated.fontSize": 13,
    "terminal.integrated.fontFamily": "Menlo"
}

九、Mac上Python开发的常用工具推荐

9.1 必备命令行工具

# tree：以树状图显示目录结构
brew install tree

# htop：交互式进程查看器（比top更好用）
brew install htop

# ripgrep：超快的文本搜索工具
brew install ripgrep

# fd：比find更好用的文件搜索工具
brew install fd

# jq：命令行JSON处理工具
brew install jq

# tldr：简化的命令帮助手册
brew install tldr

9.2 Python开发相关工具

# 虚拟环境管理
pip3 install virtualenv

# Python代码格式化
pip3 install black

# 导入排序
pip3 install isort

# 代码检查
pip3 install flake8
pip3 install pylint

# 交互式Python（比默认REPL更好用）
pip3 install ipython

9.3 IPython——更好的交互式环境

IPython是Python默认交互环境的增强版：

pip3 install ipython

# 启动ipython
ipython

IPython相比默认python交互环境的优势：

语法高亮
Tab自动补全（比默认的强大很多）
? 查看对象文档：print?
%timeit 精确计时
%run 运行Python脚本
%history 查看命令历史
支持系统命令：!ls、!pip list

# IPython中测试代码性能
In [1]: %timeit sum(range(1000000))
# 9.23 ms ± 98.7 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)

# 运行外部脚本
In [2]: %run hello.py

# 快速查看对象的方法
In [3]: import os
In [4]: os.path.join??

十、常见问题排查

10.1 “xcrun: error: invalid active developer path”

这是因为缺少Xcode命令行工具。解决方法：

xcode-select --install

在弹出的对话框中点击"安装"，等待完成即可。

10.2 “Permission denied” 权限问题

在Mac上，系统目录受到SIP（系统完整性保护）保护。安装包时可能遇到权限错误：

# 错误示例
pip3 install somepackage
# PermissionError: [Errno 13] Permission denied: '/usr/local/lib/python3.x/...'

# 不要用sudo pip install！这会污染系统环境
# 正确做法：
pip3 install --user somepackage    # 安装到用户目录
# 或者使用虚拟环境
python3 -m venv myenv
source myenv/bin/activate
pip install somepackage

绝对不要用 sudo pip install！这会把包装到系统目录，污染系统Python，而且可能与Homebrew安装的包冲突。用虚拟环境或 --user 选项。

10.3 “bad interpreter: No such file or directory”

这个错误通常发生在虚拟环境中，当虚拟环境创建时使用的Python被删除或升级后：

# 解决方法：重新创建虚拟环境
rm -rf venv
python3 -m venv venv

10.4 Intel vs Apple Silicon兼容性问题

如果你用的是M1/M2/M3芯片的Mac，绝大多数Python库现在都有原生arm64版本了。但偶尔会遇到只支持Intel的旧库：

# 检查Python的架构
python3 -c "import platform; print(platform.machine())"
# arm64 (Apple Silicon) 或 x86_64 (Intel)

# 查看某个包支持的架构
pip3 download numpy --no-deps --platform macosx
# 看下载的文件名是否包含 arm64 或 universal2

少数老旧的包可能需要Rosetta 2才能运行。安装Rosetta：

softwareupdate --install-rosetta

十一、本篇小结

✅ Mac是Python开发的理想平台。一套推荐的Mac Python开发环境配置：

Homebrew：包管理器，用 brew install python@3.12 安装Python
pyenv：多版本管理，灵活切换Python版本
iTerm2 + oh-my-zsh：让终端好用10倍
VS Code：轻量高效的代码编辑器
IPython：比默认REPL更好用的交互环境
虚拟环境：每个项目独立隔离，不污染全局Python
pip镜像源：配置清华或阿里镜像，加速下载

Mac用户在Python开发上有天然的优势——Unix环境、优秀的终端、Homebrew生态。把上述工具配置好，你的Mac就是一台完美的Python开发机。

以上就是在Mac上配置Python开发环境的完整流程的详细内容，更多关于Mac上配置Python开发环境的资料请关注脚本之家其它相关文章！