1. 让 Mac 的 Python 环境不再裸奔你有没有遇到过这种场景满怀期待地打开 Mac 终端敲下python --version屏幕上却跳出个 2.7.16 这种上世纪的老古董或者明明天天喊Python 很好上手结果光是把 Python 跑起来你就被迫经历官网下载、Discord 式 QA、路径问题三重折磨。相信我这不是你的问题。macOS 自带的 Python 只是为了支撑系统内部组件存在的苹果完全不在乎第三方开发者能不能舒服地在上面写爬虫。如果你真想本机写写脚本、做做数据分析或者跑一个机器学习 demo第一步要做的是把环境当作一个正式开发环境来认真对待。接下来这篇超长实操文会从安装方式的选型对比开始一步步带你完成 Homebrew 安装、Python 安装、pip 配置、虚拟环境搭建再到 VSCode 和 PyCharm 的解释器绑定最后送上一份常见报错排查清单。整体思路按能复现为标准每个命令都可以直接复制运行没有含糊的省略号。先说结论放在前面在当前 macOS 生态下最推荐使用 Homebrew 安装和管理 Python。到 2024 年下半年Python 3.13 已经是稳定版本Homebrew 默认的python公式指向 3.13.1。你不要自己去官网下载 pkg 安装包原因下面会讲。2. 深入了解自带 Python和 macOS 系统依赖2.1 系统自带的 Python 为什么不能随便动Mac 自带/usr/bin/python3但那是苹果为了满足系统底层工具比如xcodebuild、brew的某些依赖脚本而内置的。它基于 Apple 修改过的 Python 3.9.x 分支存在几个致命缺陷直接改它会导致系统组件故障例如 App Store 或者其他系统 UI 工具崩溃。它缺少大量第三方包pip甚至只能通过python3 -m pip这种繁琐方式调用。它不会随着 Python 官方发布新版本而自动升级。所以网上不少教程可能为了偷懒让你直接改系统 Python 的文件链接看到这种建议我建议你直接关掉页面。你要做的不是篡改系统环境而是构建一条独立的开发环境。2.2 新手最容易忽略的 Xcode Command Line Tools在装 Homebrew 之前得先安装 Xcode Command Line ToolsXcode 命令行工具。不要慌这个不是要你安装 10 多个 GB 的完整 Xcode而是只需装一个尺寸小得多的命令行工具包里面包含clang编译器、git、ssh、curl等基础组件。Homebrew 的安装脚本在编译安装包时需要用到这些。在终端输入xcode-select --install系统会弹出一个图形界面点安装然后等待下载完成即可。这个过程可能会持续几分钟视网络情况而定。如果你之前已经装过终端会提示 command line tools are already installed。这里有个常见的坑如果你还没装 Xcode CLT直接执行 Homebrew 官网的curl ... | bash -安装命令脚本十有八九会卡在Cloning into ...这一步半天没反应。这不是你安装姿势不对而是缺少基础编译链导致 Homebrew 的自检流程挂起。2.3 如何查看自己的 Mac 芯片类型和系统版本因为后面所有命令都存在 Intel 芯片和 Apple 芯片M1/M2/M3的路径差异所以先确认一下平台uname -m输出arm64Apple Silicon 处理器Homebrew 安装到/opt/homebrew/输出x86_64Intel 处理器Homebrew 安装到/usr/local/同时看一下系统版本sw_vers通常 macOS 14 都没有太多兼容性问题但如果你还停留在 macOS 10.15 CatalinaHomebrew 目前已经停止对老系统的支持需要按照官方脱机迁移文档处理。网上有个搜索热词叫 mac 系统10.15 装 Python估计就是因为老系统卡住了不少用户。这里给你交个底Catalina 想装 Homebrew最好使用 3.x 版本的 Homebrew 安装包直接用官方一键脚本大概率报错 Your macOS version is too old后面会细讲。3. 安装方式选型为什么 Homebrew 是省心最优解3.1 三种主流方案的横向对比我把目前在 Mac 上装 Python 的主流方案拉出来做个对比你看完就明白差距了。方案安装方式更新方式卸载难度多版本共存适合人群官网 DMG/pkg图形化一路 Next手动下载安装中容易残留签名文件极难只想装一次就跑 demo 的萌新Homebrewbrew install pythonbrew upgrade一条命令极低brew uninstall --ignore-dependencies python普通可通过 brew 切换大多数开发者和进阶者Pyenvpyenv install 3.12.3pyenv install指定新版本低可直接删除目录极强项目级切换多项目并行、老项目维护者官网的安装器在双击安装时会弹出一个验证开发者的对话框很多人不知道在 macOS 的隐私与安全性设置里还需要额外点一次仍要打开否则直接安装就报错。就算安装完成系统路径里python和python3的指向也可能和你的预期不一致。卸载的时候更痛苦/Library/Frameworks/Python.framework、/usr/local/bin下面的符号链接一个不留神就会残留在系统里复发时都不知道该删哪个。而 Homebrew 的思路就清晰多了既然系统内置版本不好碰就单独开辟一个 Homebrew 目录Intel 在/usr/localApple Silicon 在/opt/homebrew把 Python 完整装进这个目录里再用符号链接把python3、pip3暴露到 PATH 中。brew upgrade之后之前通过 pip 装的包可能要重新编但 Python 本体永远是干净可控的。至于 Pyenv它本质上是一个版本切管器通过修改PATH优先级让你在当前目录穿不同的 Python 版本。如果你以后要维护的项目既有 Python 2.7 老代码又有 3.12 新项目那 Pyenv 是救星。但如果只有一个需求上来就装 Pyenv 会有点杀鸡用牛刀。3.2 为什么不推荐直接使用官网下载的 PKG 安装器很多新手看到 Python 官网有专门的 macOS 64-bit universal2 installer就按照 Windows 习惯一路下一步。安装时它会给一个提示安装位置在/Library/Frameworks/Python.framework/Versions/3.12/。问题就出在这里它的执行文件虽然被软链到了python3.12但 Python 包的库文件路径和字节码缓存目录都会指向/Library/Frameworks当你权值不够或者目录权限被其它软件的安装包覆盖时包管理器就会开始胡言乱语。还有一个更阴间的现象系统里面同时存在多个 Python 的路径比如/usr/bin/python3、/Library/Frameworks/.../bin/python3、/opt/homebrew/bin/python3。由于 shell 的PATH是按顺序查找的如果官网的 后台进程先找到了然后更新 pip 时它直接调用pip3 install --upgrade pip更新到不兼容版本到时候排查 node、python 冲突你会极其痛苦。所以干脆别给它混进 PATH 的机会。另外如果你真想用官方安装器我建议安装完成后额外执行sudo python3 -m pip install --upgrade --force-reinstall pip然后清理 PyPI 缓存pip3 cache remove *但说实话这套流程对于小白玩家来说远不如brew install python顺滑。4. 从零到一完整走一遍 Homebrew Python 安装4.1 Homebrew 的安装脚本与常见报错处理在终端粘贴如下命令/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)如果你的网络通畅大概两三分钟后就会看到Press RETURN to continue or any other key to abort的提示。此时按回车即可。安装完成后建议执行brew doctor检查环境是否有问题。同时根据是 Apple Silicon 还是 Intel把 Homebrew 加到 PATH 里。在.zprofile中追加echo eval $(/opt/homebrew/bin/brew shellenv) ~/.zprofile eval $(/opt/homebrew/bin/brew shellenv)Intel 机器则使用echo eval $(/usr/local/bin/brew shellenv) ~/.zprofile eval $(/usr/local/bin/brew shellenv)这部分和之前讲过的搜索热词mac安装homebrew报错紧密相关。如果你在安装过程中碰到经典的curl: (35) LibreSSL SSL_connect: SSL_ERROR_SYSCALL或者fatal: unable to access https://github.com/Homebrew/brew/: LibreSSL SSL_connect: SSL_ERROR_SYSCALL in connection to github.com:443。原因多数有两个你本地的 git 或者 curl 走了历史遗留的代理设置。路由器或者 DNS 解析有问题。排查方式先查代理env | grep -i proxy git config --global --list | grep -i proxy如果有输出说明之前某个软件往 git 全局配置里写了代理。不知道怎么处理的话可以直接取消设置git config --global --unset http.proxy git config --global --unset https.proxy如果取消后仍无法连接建议检查/etc/hosts里是否有屏蔽 GitHub 的条目如果有删掉对应行。这一步只要你不是在公司统一管控的网络下基本都能解决。4.2 通过 Homebrew 安装 Python 正主有了 Homebrew安装 Python 就是一键的事brew install python不要担心它没有设置python命令因为python这个名字和系统自带的 Python 存在冲突Homebrew 默认只创建python3的符号链接。运行python3 --version你就可以看到类似Python 3.13.1的输出。这里要注意官方已经彻底废弃 Python 2 时代的python指向直接让python等价于python3是新时代的主流做法。不少新手喜欢往~/.zshrc里加一句alias pythonpython3我建议晚点再这么做先把基本概念理清楚否则后面会出现脚本头#!/usr/bin/env python没法执行的问题。安装路径位于$(brew --prefix)/opt/python/libexec/bin但python3已经被软链接到了/opt/homebrew/opt/python/libexec/bin里面pip3也一并被链接好不需要手动设置。4.3 顺手配置 pip 国内镜像站加速装完 Python 之后第一件事往往是pip install requests。但默认的 PyPI 源在海外国内速度慢到令人发指还可能连接超时。虽然不是必须但要是想顺畅一点可以配置国内镜像源个人用清华源或者阿里源都行。mkdir -p ~/.pip cat EOF ~/.pip/pip.conf [global] index-url https://pypi.tuna.tsinghua.edu.cn/simple [install] trusted-host pypi.tuna.tsinghua.edu.cn EOF网上有个热搜免费python源码大全很多人在下载源代码后执行的第一个语句就是pip install -r requirements.txt如果这一步卡住多半是因为没配镜像源。配上之后速度可以提升好几倍。5. 安装完必做的三件事隔离、路径和别名这部分非常关键因为很多人卡在明明安装成功了一跑代码却报错本质就是这三个方面没配好。5.1 解除 pip 的外部环境管理限制新版 Python 3.11 为了防止用户绕过系统包管理器直接给 Python 塞包默认加了EXTERNALLY-MANAGED标记直接执行pip3 install requests大概率会看到这种提示error: externally-managed-environment × This environment is externally managed这个提示的本意是好的阻止你往/usr/local或者/opt/homebrew目录里乱塞包。但你要真想给当前解释器装包无非就两条路创建一个虚拟环境在虚拟环境里装包。修改pip.conf加入break-system-packages true。我建议只走第一条路虚拟环境才是现代 Python 开发的基石。这里演示一下怎么操作cd ~/myproject python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip激活之后你会发现命令前的提示符多了一个(.venv)然后再pip install就不会受到任何干扰了。后面运行项目时只需要先执行source .venv/bin/activate退出环境则执行deactivate。5.2 处理好PATH里的优先级问题如果你在安装 Homebrew 之前用的是官网安装器很可能会出现which python3指向/Library/Frameworks/Python.framework/Versions/3.12/bin/python3而不是你想用的/opt/homebrew/bin/python3。这个时候要对.zshrc进行优先级排序让 Homebrew 的路径排在前头。export PATH/opt/homebrew/bin:$PATH export PATH/opt/homebrew/opt/python/libexec/bin:$PATH注意$PATH放在后面代表前面添加的目录优先级更高。装完这几个 export 之后执行source ~/.zshrc再运行which python3检查。5.3 使用 alias 还是不用我说说个人心得关于alias pythonpython3这是一把双刃剑。给你列几个场景我本地装了一堆第三方命令行工具它们会在执行时调用python但这些工具只支持 Python 3。某些老脚本的 shebang 是#!/usr/bin/env python如果不做别名脚本会去调系统自带的 Python 2.7直接崩掉。所以我的做法是设置alias pythonpython3但它只是一个 shell 层面的简化并不改变系统的全局映射。你可以把下面这行写进~/.zshrcalias pythonpython3不过要注意如果你使用 Pyenv 管理多个 Python 版本那么 Pyenv 会自动接管 python 命令别名反而会干扰 Pyenv 的 shims所以建议在单独使用 Homebrew 的时候再加别名。6. VSCode 和 PyCharm 配置 Python 解释器的实用技巧安装完环境最后一步就是让编辑器能够找到我们刚才装好的解释器因为热词里使用频率最高的就是vscode python环境配置和pycharm配置python环境。6.1 VSCode 的配置路径在 VSCode 中按Cmd Shift P打开命令面板输入Python: Select Interpreter然后选择/opt/homebrew/bin/python3即可。但如果你有虚拟环境更推荐直接选择项目下的.venv/bin/python这样 VSCode 的终端集成器也会自动激活环境。另外建议安装这几个扩展插件这个列表直接参考行业通行的配置公约插件名称用途Python (microsoft)提供智能感知、断点调试、代码格式化Pylance类型检查和补全配套 Python 主插件使用Ruff (charliermarsh)极快的 Python 代码检查与自动修复Jupyter运行 .ipynb 文件数据分析和教学场景然后在settings.json中给当前项目指定默认解释器{ python.defaultInterpreterPath: ${workspaceFolder}/.venv/bin/python, python.terminal.activateEnvironment: true, python.formatting.provider: black }最容易被忽略的是python.terminal.activateEnvironment这一项。如果设置为 false即使你选择了虚拟环境解释器F5 运行时依然会找不到刚装的依赖包。另一个坑是热词mac cursor很多人在用 Cursor 编辑器。Cursor 基于 VSCode 内核配置 Python 解释器的入口和上述完全一致只是它更倾向于 AI 自动补全。你只要在 Cursor 里Cmd Shift P执行同样的命令能正常识别虚拟环境AI 模型的输出也会大幅提升准确率。6.2 PyCharm 的配置路径PyCharm 安装后第一次打开项目它会自动探测系统解释器。如果没有自动识别就进入Settings-Project: your_project-Python Interpreter点击齿轮图标选择Add Local Interpreter。在弹窗里选择Existing并定位到你的虚拟环境路径~/myproject/.venv/bin/pythonPyCharm 会为项目自动生成一份 Python SDK 配置。如果你开着多个项目就建议每个项目单独建一套虚拟环境这样互不干扰。社区版和 Professional 版本在这个配置上的逻辑是一样的完全不用改。PyCharm 还有一个很实用的地方在Settings-Tools-Python Integrated Tools里可以将默认测试运行器设置成pytest以后写单测的时候点击直接运行不用每次在控制台手动敲pytest命令。6.3 配置完依然报错Last resort如果反复确认解释器路径没错但代码还是报ModuleNotFoundError那很可能是有多个 Python 共存导致 pip 装到了一个环境而解释器查到的是另一个环境。可以用这两行命令快速核对python3 -c import sys; print(sys.executable) pip3 -V确认两者路径前缀一致就说明环境没啥问题。如果发现路径不一致说明你把 pip 和 Python 混装了最简单的做法是直接删掉当前虚拟环境重建一个rm -rf .venv python3 -m venv .venv7. 进阶玩法用 Pyenv 管理多个 Python 版本7.1 为什么还需要 Pyenv热词里出现频率最高的就是python入门和python教程但入门阶段一般不会被多版本问题折磨。然而当你开始接手公司老项目时你就会体验到一个项目要 Python 3.7另一个要 Python 3.11 的版本地狱。此时 Homebrew 只切换系统全局版本无法满足。Pyenv 能让你在一个文件夹内临时覆盖 Python 版本不污染全局简直法宝。安装 Pyenv用 Homebrew 最方便brew install pyenv pyenv install 3.10.14 pyenv install 3.12.3安装完在~/.zshrc里加入export PYENV_ROOT$HOME/.pyenv export PATH$PYENV_ROOT/bin:$PATH eval $(pyenv init --path) eval $(pyenv init -)保存后重新加载 shell 配置然后设定全局版本pyenv global 3.12.3在某个项目里临时指定 3.10cd ~/legacy_project pyenv local 3.10.14 python --version # 输出 3.10.147.2 Pyenv 与 Homebrew python 的共存策略Pyenv 会接管python命令的 shim而 Homebrew 的python在/opt/homebrew/bin/python3。只要你没有把别名pythonpython3硬生生塞进.zshrcPyenv 完全兼容 Homebrew。你可以让 Pyenv 管理多版本解释器而 Homebrew 专心维护第三方底层工具库。7.3 编译环境的坑第一次使用pyenv install 3.12.3时很有可能遇到zipimport.ZipImportError: cant decompress data或configure: error: C compiler cannot create executables。这同样指向缺少 Xcode 命令行工具。所以在安装 pyenv 之前先确保 Xcode CLT 已经安装完成并且执行过以下兼容性命令sudo xcodebuild -license accept如果你不想使用系统 Xcode 的全量授权也可以只安装独立命令行工具包。另外 pyenv 默认源码编译耗时较长建议设置环境变量使用国内镜像export PYTHON_BUILD_MIRROR_URLhttps://npm.taobao.org/mirrors/python/虽然这个镜像站现在改名成了 npmmirror但历史上最好用的用法就是用淘宝镜像来加速 Python 源码编译。如果你希望直接安装预编译版本可以安装pyenv-python-build相关的第三方扩展不过会对稳定性有一定损失。8. 安装完常见的四个运行报错与排查心得8.1 macOS 无法验证开发者的处理这个报错出现的场景一般是第一次执行brew命令或者别人发给你一个预编译的 Python 包。解决办法有两种一种是在系统设置里打开隐私与安全性点仍要打开另一种是干脆移除 quarantine 属性xattr -d com.apple.quarantine /path/to/your/file对于 Homebrew 本身一般不需要做这个操作因为它安装的所有二进制都有开发者签名。但如果你真的倒霉在终端执行brew时遇到Killed: 9这种字样大概率是 macOS 的 Gatekeeper 在拦截请优先到系统设置里打开对应的软件许可。8.2 zsh: command not found: python 的应对如果你刚装完 Homebrew Python在终端输入python报错不要慌。请检查你是否安装的是 3.x以及你是否在~/.zshrc中加入了别名。如果是全新的终端窗口还需要检查source ~/.zshrc是否执行过。最稳妥的方式是直接用python3运行程序或者记住要加别名。8.3 pip command not found 的处理Homebrew 安装的 Python 配套了 pip3但很多用户去执行pip时找不到命令。因为pip这个裸命令同样没有被系统链接。想用无脑舒服地执行pip除了alias pippip3我更推荐直接使用python3 -m pip这种调法这样无论环境怎么折腾都能找到正确解释器对应的 pip。当你在多个 Python 版本下工作时这点极其重要。8.4 环境变量 PATH 冲突一个真实的踩坑案例之前我本机装了 Java、Maven、Python、Node 四套环境为了省事把所有 bin 目录都写进了.zshrc结果发现偶尔mvn -v正常python3 -V正常但pip3 install lxml时就报错说找不到Python.h。排查半天发现是 PATH 里提前加载了一个基于 Anaconda 的 Python 库目录导致编译头文件指向了错的路径。后面我认真整理过 PATH 的写入顺序统一约定# 置于最前 export PATH/opt/homebrew/bin:$PATH export PATH/usr/local/bin:$PATH # 最后追加其他工具同时使用brew cleanup清掉了多余的旧版本包。现在我的本机运行酷炫的 Python 程序几乎不出现莫名其妙的编译错误。9. 最后分享两个小习惯装环境这件事才真正闭环第一个小习惯是给每个 Python 工程都建独立虚拟环境。哪怕你只是临时跑一个脚本也尽量执行python3 -m venv .venv source .venv/bin/activate。这样即使某一个项目的依赖包升级到不兼容也不会把整个系统的模块链弄崩。虚拟环境不会占用特别多空间却能换来极大的心理安全感。第二个小习惯是定期给 Homebrew 本身做一次体检brew doctor brew upgrade brew cleanup --pruneallbrew doctor会帮你发现 PATH 冲突、旧版本残留、权限异常等问题。我见过很多报错求助帖其实执行一次brew doctor后按提示修完就全好了可惜大部分新人都卡在第一步没有诊断意识。关于安装时是否要加一串sudo的问题我的建议是 Homebrew 整个流程都不应该使用 sudo。如果脚本提示你输入管理员密码那说明目录权限已经被之前的杂技操作搅乱了。这时宁可初始化回滚重装 Homebrew也不要硬着头皮以 root 身份污染目录。个人经验里果断重装 Homebrew 省下的排错时间远超你重新下载的时间。
Mac上Python环境搭建指南：Homebrew+虚拟环境+编辑器配置
1. 让 Mac 的 Python 环境不再裸奔你有没有遇到过这种场景满怀期待地打开 Mac 终端敲下python --version屏幕上却跳出个 2.7.16 这种上世纪的老古董或者明明天天喊Python 很好上手结果光是把 Python 跑起来你就被迫经历官网下载、Discord 式 QA、路径问题三重折磨。相信我这不是你的问题。macOS 自带的 Python 只是为了支撑系统内部组件存在的苹果完全不在乎第三方开发者能不能舒服地在上面写爬虫。如果你真想本机写写脚本、做做数据分析或者跑一个机器学习 demo第一步要做的是把环境当作一个正式开发环境来认真对待。接下来这篇超长实操文会从安装方式的选型对比开始一步步带你完成 Homebrew 安装、Python 安装、pip 配置、虚拟环境搭建再到 VSCode 和 PyCharm 的解释器绑定最后送上一份常见报错排查清单。整体思路按能复现为标准每个命令都可以直接复制运行没有含糊的省略号。先说结论放在前面在当前 macOS 生态下最推荐使用 Homebrew 安装和管理 Python。到 2024 年下半年Python 3.13 已经是稳定版本Homebrew 默认的python公式指向 3.13.1。你不要自己去官网下载 pkg 安装包原因下面会讲。2. 深入了解自带 Python和 macOS 系统依赖2.1 系统自带的 Python 为什么不能随便动Mac 自带/usr/bin/python3但那是苹果为了满足系统底层工具比如xcodebuild、brew的某些依赖脚本而内置的。它基于 Apple 修改过的 Python 3.9.x 分支存在几个致命缺陷直接改它会导致系统组件故障例如 App Store 或者其他系统 UI 工具崩溃。它缺少大量第三方包pip甚至只能通过python3 -m pip这种繁琐方式调用。它不会随着 Python 官方发布新版本而自动升级。所以网上不少教程可能为了偷懒让你直接改系统 Python 的文件链接看到这种建议我建议你直接关掉页面。你要做的不是篡改系统环境而是构建一条独立的开发环境。2.2 新手最容易忽略的 Xcode Command Line Tools在装 Homebrew 之前得先安装 Xcode Command Line ToolsXcode 命令行工具。不要慌这个不是要你安装 10 多个 GB 的完整 Xcode而是只需装一个尺寸小得多的命令行工具包里面包含clang编译器、git、ssh、curl等基础组件。Homebrew 的安装脚本在编译安装包时需要用到这些。在终端输入xcode-select --install系统会弹出一个图形界面点安装然后等待下载完成即可。这个过程可能会持续几分钟视网络情况而定。如果你之前已经装过终端会提示 command line tools are already installed。这里有个常见的坑如果你还没装 Xcode CLT直接执行 Homebrew 官网的curl ... | bash -安装命令脚本十有八九会卡在Cloning into ...这一步半天没反应。这不是你安装姿势不对而是缺少基础编译链导致 Homebrew 的自检流程挂起。2.3 如何查看自己的 Mac 芯片类型和系统版本因为后面所有命令都存在 Intel 芯片和 Apple 芯片M1/M2/M3的路径差异所以先确认一下平台uname -m输出arm64Apple Silicon 处理器Homebrew 安装到/opt/homebrew/输出x86_64Intel 处理器Homebrew 安装到/usr/local/同时看一下系统版本sw_vers通常 macOS 14 都没有太多兼容性问题但如果你还停留在 macOS 10.15 CatalinaHomebrew 目前已经停止对老系统的支持需要按照官方脱机迁移文档处理。网上有个搜索热词叫 mac 系统10.15 装 Python估计就是因为老系统卡住了不少用户。这里给你交个底Catalina 想装 Homebrew最好使用 3.x 版本的 Homebrew 安装包直接用官方一键脚本大概率报错 Your macOS version is too old后面会细讲。3. 安装方式选型为什么 Homebrew 是省心最优解3.1 三种主流方案的横向对比我把目前在 Mac 上装 Python 的主流方案拉出来做个对比你看完就明白差距了。方案安装方式更新方式卸载难度多版本共存适合人群官网 DMG/pkg图形化一路 Next手动下载安装中容易残留签名文件极难只想装一次就跑 demo 的萌新Homebrewbrew install pythonbrew upgrade一条命令极低brew uninstall --ignore-dependencies python普通可通过 brew 切换大多数开发者和进阶者Pyenvpyenv install 3.12.3pyenv install指定新版本低可直接删除目录极强项目级切换多项目并行、老项目维护者官网的安装器在双击安装时会弹出一个验证开发者的对话框很多人不知道在 macOS 的隐私与安全性设置里还需要额外点一次仍要打开否则直接安装就报错。就算安装完成系统路径里python和python3的指向也可能和你的预期不一致。卸载的时候更痛苦/Library/Frameworks/Python.framework、/usr/local/bin下面的符号链接一个不留神就会残留在系统里复发时都不知道该删哪个。而 Homebrew 的思路就清晰多了既然系统内置版本不好碰就单独开辟一个 Homebrew 目录Intel 在/usr/localApple Silicon 在/opt/homebrew把 Python 完整装进这个目录里再用符号链接把python3、pip3暴露到 PATH 中。brew upgrade之后之前通过 pip 装的包可能要重新编但 Python 本体永远是干净可控的。至于 Pyenv它本质上是一个版本切管器通过修改PATH优先级让你在当前目录穿不同的 Python 版本。如果你以后要维护的项目既有 Python 2.7 老代码又有 3.12 新项目那 Pyenv 是救星。但如果只有一个需求上来就装 Pyenv 会有点杀鸡用牛刀。3.2 为什么不推荐直接使用官网下载的 PKG 安装器很多新手看到 Python 官网有专门的 macOS 64-bit universal2 installer就按照 Windows 习惯一路下一步。安装时它会给一个提示安装位置在/Library/Frameworks/Python.framework/Versions/3.12/。问题就出在这里它的执行文件虽然被软链到了python3.12但 Python 包的库文件路径和字节码缓存目录都会指向/Library/Frameworks当你权值不够或者目录权限被其它软件的安装包覆盖时包管理器就会开始胡言乱语。还有一个更阴间的现象系统里面同时存在多个 Python 的路径比如/usr/bin/python3、/Library/Frameworks/.../bin/python3、/opt/homebrew/bin/python3。由于 shell 的PATH是按顺序查找的如果官网的 后台进程先找到了然后更新 pip 时它直接调用pip3 install --upgrade pip更新到不兼容版本到时候排查 node、python 冲突你会极其痛苦。所以干脆别给它混进 PATH 的机会。另外如果你真想用官方安装器我建议安装完成后额外执行sudo python3 -m pip install --upgrade --force-reinstall pip然后清理 PyPI 缓存pip3 cache remove *但说实话这套流程对于小白玩家来说远不如brew install python顺滑。4. 从零到一完整走一遍 Homebrew Python 安装4.1 Homebrew 的安装脚本与常见报错处理在终端粘贴如下命令/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)如果你的网络通畅大概两三分钟后就会看到Press RETURN to continue or any other key to abort的提示。此时按回车即可。安装完成后建议执行brew doctor检查环境是否有问题。同时根据是 Apple Silicon 还是 Intel把 Homebrew 加到 PATH 里。在.zprofile中追加echo eval $(/opt/homebrew/bin/brew shellenv) ~/.zprofile eval $(/opt/homebrew/bin/brew shellenv)Intel 机器则使用echo eval $(/usr/local/bin/brew shellenv) ~/.zprofile eval $(/usr/local/bin/brew shellenv)这部分和之前讲过的搜索热词mac安装homebrew报错紧密相关。如果你在安装过程中碰到经典的curl: (35) LibreSSL SSL_connect: SSL_ERROR_SYSCALL或者fatal: unable to access https://github.com/Homebrew/brew/: LibreSSL SSL_connect: SSL_ERROR_SYSCALL in connection to github.com:443。原因多数有两个你本地的 git 或者 curl 走了历史遗留的代理设置。路由器或者 DNS 解析有问题。排查方式先查代理env | grep -i proxy git config --global --list | grep -i proxy如果有输出说明之前某个软件往 git 全局配置里写了代理。不知道怎么处理的话可以直接取消设置git config --global --unset http.proxy git config --global --unset https.proxy如果取消后仍无法连接建议检查/etc/hosts里是否有屏蔽 GitHub 的条目如果有删掉对应行。这一步只要你不是在公司统一管控的网络下基本都能解决。4.2 通过 Homebrew 安装 Python 正主有了 Homebrew安装 Python 就是一键的事brew install python不要担心它没有设置python命令因为python这个名字和系统自带的 Python 存在冲突Homebrew 默认只创建python3的符号链接。运行python3 --version你就可以看到类似Python 3.13.1的输出。这里要注意官方已经彻底废弃 Python 2 时代的python指向直接让python等价于python3是新时代的主流做法。不少新手喜欢往~/.zshrc里加一句alias pythonpython3我建议晚点再这么做先把基本概念理清楚否则后面会出现脚本头#!/usr/bin/env python没法执行的问题。安装路径位于$(brew --prefix)/opt/python/libexec/bin但python3已经被软链接到了/opt/homebrew/opt/python/libexec/bin里面pip3也一并被链接好不需要手动设置。4.3 顺手配置 pip 国内镜像站加速装完 Python 之后第一件事往往是pip install requests。但默认的 PyPI 源在海外国内速度慢到令人发指还可能连接超时。虽然不是必须但要是想顺畅一点可以配置国内镜像源个人用清华源或者阿里源都行。mkdir -p ~/.pip cat EOF ~/.pip/pip.conf [global] index-url https://pypi.tuna.tsinghua.edu.cn/simple [install] trusted-host pypi.tuna.tsinghua.edu.cn EOF网上有个热搜免费python源码大全很多人在下载源代码后执行的第一个语句就是pip install -r requirements.txt如果这一步卡住多半是因为没配镜像源。配上之后速度可以提升好几倍。5. 安装完必做的三件事隔离、路径和别名这部分非常关键因为很多人卡在明明安装成功了一跑代码却报错本质就是这三个方面没配好。5.1 解除 pip 的外部环境管理限制新版 Python 3.11 为了防止用户绕过系统包管理器直接给 Python 塞包默认加了EXTERNALLY-MANAGED标记直接执行pip3 install requests大概率会看到这种提示error: externally-managed-environment × This environment is externally managed这个提示的本意是好的阻止你往/usr/local或者/opt/homebrew目录里乱塞包。但你要真想给当前解释器装包无非就两条路创建一个虚拟环境在虚拟环境里装包。修改pip.conf加入break-system-packages true。我建议只走第一条路虚拟环境才是现代 Python 开发的基石。这里演示一下怎么操作cd ~/myproject python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip激活之后你会发现命令前的提示符多了一个(.venv)然后再pip install就不会受到任何干扰了。后面运行项目时只需要先执行source .venv/bin/activate退出环境则执行deactivate。5.2 处理好PATH里的优先级问题如果你在安装 Homebrew 之前用的是官网安装器很可能会出现which python3指向/Library/Frameworks/Python.framework/Versions/3.12/bin/python3而不是你想用的/opt/homebrew/bin/python3。这个时候要对.zshrc进行优先级排序让 Homebrew 的路径排在前头。export PATH/opt/homebrew/bin:$PATH export PATH/opt/homebrew/opt/python/libexec/bin:$PATH注意$PATH放在后面代表前面添加的目录优先级更高。装完这几个 export 之后执行source ~/.zshrc再运行which python3检查。5.3 使用 alias 还是不用我说说个人心得关于alias pythonpython3这是一把双刃剑。给你列几个场景我本地装了一堆第三方命令行工具它们会在执行时调用python但这些工具只支持 Python 3。某些老脚本的 shebang 是#!/usr/bin/env python如果不做别名脚本会去调系统自带的 Python 2.7直接崩掉。所以我的做法是设置alias pythonpython3但它只是一个 shell 层面的简化并不改变系统的全局映射。你可以把下面这行写进~/.zshrcalias pythonpython3不过要注意如果你使用 Pyenv 管理多个 Python 版本那么 Pyenv 会自动接管 python 命令别名反而会干扰 Pyenv 的 shims所以建议在单独使用 Homebrew 的时候再加别名。6. VSCode 和 PyCharm 配置 Python 解释器的实用技巧安装完环境最后一步就是让编辑器能够找到我们刚才装好的解释器因为热词里使用频率最高的就是vscode python环境配置和pycharm配置python环境。6.1 VSCode 的配置路径在 VSCode 中按Cmd Shift P打开命令面板输入Python: Select Interpreter然后选择/opt/homebrew/bin/python3即可。但如果你有虚拟环境更推荐直接选择项目下的.venv/bin/python这样 VSCode 的终端集成器也会自动激活环境。另外建议安装这几个扩展插件这个列表直接参考行业通行的配置公约插件名称用途Python (microsoft)提供智能感知、断点调试、代码格式化Pylance类型检查和补全配套 Python 主插件使用Ruff (charliermarsh)极快的 Python 代码检查与自动修复Jupyter运行 .ipynb 文件数据分析和教学场景然后在settings.json中给当前项目指定默认解释器{ python.defaultInterpreterPath: ${workspaceFolder}/.venv/bin/python, python.terminal.activateEnvironment: true, python.formatting.provider: black }最容易被忽略的是python.terminal.activateEnvironment这一项。如果设置为 false即使你选择了虚拟环境解释器F5 运行时依然会找不到刚装的依赖包。另一个坑是热词mac cursor很多人在用 Cursor 编辑器。Cursor 基于 VSCode 内核配置 Python 解释器的入口和上述完全一致只是它更倾向于 AI 自动补全。你只要在 Cursor 里Cmd Shift P执行同样的命令能正常识别虚拟环境AI 模型的输出也会大幅提升准确率。6.2 PyCharm 的配置路径PyCharm 安装后第一次打开项目它会自动探测系统解释器。如果没有自动识别就进入Settings-Project: your_project-Python Interpreter点击齿轮图标选择Add Local Interpreter。在弹窗里选择Existing并定位到你的虚拟环境路径~/myproject/.venv/bin/pythonPyCharm 会为项目自动生成一份 Python SDK 配置。如果你开着多个项目就建议每个项目单独建一套虚拟环境这样互不干扰。社区版和 Professional 版本在这个配置上的逻辑是一样的完全不用改。PyCharm 还有一个很实用的地方在Settings-Tools-Python Integrated Tools里可以将默认测试运行器设置成pytest以后写单测的时候点击直接运行不用每次在控制台手动敲pytest命令。6.3 配置完依然报错Last resort如果反复确认解释器路径没错但代码还是报ModuleNotFoundError那很可能是有多个 Python 共存导致 pip 装到了一个环境而解释器查到的是另一个环境。可以用这两行命令快速核对python3 -c import sys; print(sys.executable) pip3 -V确认两者路径前缀一致就说明环境没啥问题。如果发现路径不一致说明你把 pip 和 Python 混装了最简单的做法是直接删掉当前虚拟环境重建一个rm -rf .venv python3 -m venv .venv7. 进阶玩法用 Pyenv 管理多个 Python 版本7.1 为什么还需要 Pyenv热词里出现频率最高的就是python入门和python教程但入门阶段一般不会被多版本问题折磨。然而当你开始接手公司老项目时你就会体验到一个项目要 Python 3.7另一个要 Python 3.11 的版本地狱。此时 Homebrew 只切换系统全局版本无法满足。Pyenv 能让你在一个文件夹内临时覆盖 Python 版本不污染全局简直法宝。安装 Pyenv用 Homebrew 最方便brew install pyenv pyenv install 3.10.14 pyenv install 3.12.3安装完在~/.zshrc里加入export PYENV_ROOT$HOME/.pyenv export PATH$PYENV_ROOT/bin:$PATH eval $(pyenv init --path) eval $(pyenv init -)保存后重新加载 shell 配置然后设定全局版本pyenv global 3.12.3在某个项目里临时指定 3.10cd ~/legacy_project pyenv local 3.10.14 python --version # 输出 3.10.147.2 Pyenv 与 Homebrew python 的共存策略Pyenv 会接管python命令的 shim而 Homebrew 的python在/opt/homebrew/bin/python3。只要你没有把别名pythonpython3硬生生塞进.zshrcPyenv 完全兼容 Homebrew。你可以让 Pyenv 管理多版本解释器而 Homebrew 专心维护第三方底层工具库。7.3 编译环境的坑第一次使用pyenv install 3.12.3时很有可能遇到zipimport.ZipImportError: cant decompress data或configure: error: C compiler cannot create executables。这同样指向缺少 Xcode 命令行工具。所以在安装 pyenv 之前先确保 Xcode CLT 已经安装完成并且执行过以下兼容性命令sudo xcodebuild -license accept如果你不想使用系统 Xcode 的全量授权也可以只安装独立命令行工具包。另外 pyenv 默认源码编译耗时较长建议设置环境变量使用国内镜像export PYTHON_BUILD_MIRROR_URLhttps://npm.taobao.org/mirrors/python/虽然这个镜像站现在改名成了 npmmirror但历史上最好用的用法就是用淘宝镜像来加速 Python 源码编译。如果你希望直接安装预编译版本可以安装pyenv-python-build相关的第三方扩展不过会对稳定性有一定损失。8. 安装完常见的四个运行报错与排查心得8.1 macOS 无法验证开发者的处理这个报错出现的场景一般是第一次执行brew命令或者别人发给你一个预编译的 Python 包。解决办法有两种一种是在系统设置里打开隐私与安全性点仍要打开另一种是干脆移除 quarantine 属性xattr -d com.apple.quarantine /path/to/your/file对于 Homebrew 本身一般不需要做这个操作因为它安装的所有二进制都有开发者签名。但如果你真的倒霉在终端执行brew时遇到Killed: 9这种字样大概率是 macOS 的 Gatekeeper 在拦截请优先到系统设置里打开对应的软件许可。8.2 zsh: command not found: python 的应对如果你刚装完 Homebrew Python在终端输入python报错不要慌。请检查你是否安装的是 3.x以及你是否在~/.zshrc中加入了别名。如果是全新的终端窗口还需要检查source ~/.zshrc是否执行过。最稳妥的方式是直接用python3运行程序或者记住要加别名。8.3 pip command not found 的处理Homebrew 安装的 Python 配套了 pip3但很多用户去执行pip时找不到命令。因为pip这个裸命令同样没有被系统链接。想用无脑舒服地执行pip除了alias pippip3我更推荐直接使用python3 -m pip这种调法这样无论环境怎么折腾都能找到正确解释器对应的 pip。当你在多个 Python 版本下工作时这点极其重要。8.4 环境变量 PATH 冲突一个真实的踩坑案例之前我本机装了 Java、Maven、Python、Node 四套环境为了省事把所有 bin 目录都写进了.zshrc结果发现偶尔mvn -v正常python3 -V正常但pip3 install lxml时就报错说找不到Python.h。排查半天发现是 PATH 里提前加载了一个基于 Anaconda 的 Python 库目录导致编译头文件指向了错的路径。后面我认真整理过 PATH 的写入顺序统一约定# 置于最前 export PATH/opt/homebrew/bin:$PATH export PATH/usr/local/bin:$PATH # 最后追加其他工具同时使用brew cleanup清掉了多余的旧版本包。现在我的本机运行酷炫的 Python 程序几乎不出现莫名其妙的编译错误。9. 最后分享两个小习惯装环境这件事才真正闭环第一个小习惯是给每个 Python 工程都建独立虚拟环境。哪怕你只是临时跑一个脚本也尽量执行python3 -m venv .venv source .venv/bin/activate。这样即使某一个项目的依赖包升级到不兼容也不会把整个系统的模块链弄崩。虚拟环境不会占用特别多空间却能换来极大的心理安全感。第二个小习惯是定期给 Homebrew 本身做一次体检brew doctor brew upgrade brew cleanup --pruneallbrew doctor会帮你发现 PATH 冲突、旧版本残留、权限异常等问题。我见过很多报错求助帖其实执行一次brew doctor后按提示修完就全好了可惜大部分新人都卡在第一步没有诊断意识。关于安装时是否要加一串sudo的问题我的建议是 Homebrew 整个流程都不应该使用 sudo。如果脚本提示你输入管理员密码那说明目录权限已经被之前的杂技操作搅乱了。这时宁可初始化回滚重装 Homebrew也不要硬着头皮以 root 身份污染目录。个人经验里果断重装 Homebrew 省下的排错时间远超你重新下载的时间。
