在 macOS 上安装 ESP-IDF 及工具链

[中文]

本章节将介绍如何使用 ESP-IDF 安装管理器 (EIM) 在 macOS 上安装 ESP-IDF 及其所需工具。

备注

本章节描述了 ESP-IDF v6.0 及以上版本的默认和推荐安装方式。如使用 ESP-IDF v6.0 之前版本的默认安装方式，请参考 macOS 上的传统安装方法。

第一步：安装依赖包

通过 Homebrew 安装所需的依赖包：

brew install libgcrypt glib pixman sdl2 libslirp dfu-util cmake python

备注

ESP-IDF 要求 Python 版本至少为 3.10。

但如需使用 EIM 进行 离线安装，则必须使用 Python 3.11 或更高版本。

第二步：安装 EIM

将 EIM 仓库添加到 Homebrew 中，以便后续使用 Homebrew 安装 EIM：

brew tap espressif/eim

然后，通过 Homebrew 安装 EIM 的图形用户界面 (GUI) 或命令行界面 (CLI)：

  • GUI：
    brew install --cask eim-gui
  • CLI：
    brew install eim

备注

通过 Homebrew 安装 EIM 便于后续升级更新。

您也可以从 Espressif 下载页面 下载适用于 macOS 的 EIM 安装包，该页面提供了 CLI 和 GUI 版本的在线和离线安装程序。

第三步：使用 EIM 安装 ESP-IDF

您可以使用以下任一方法安装 ESP-IDF 及其所需工具，具体取决于您的需求：

使用 EIM GUI 在线安装

打开 ESP-IDF 安装管理器应用程序 eim。

之后，在 新安装 下点击 开始安装。

EIM 开始安装

EIM 开始安装

备注

如果之前未安装过 ESP-IDF，GUI 中不会显示 管理安装，仅显示 新安装 选项。

在 简易安装 下，点击 开始简易安装，使用默认设置安装最新稳定版本的 ESP-IDF。

EIM 简易安装

EIM 简易安装

如果所有先决条件和路径检查都通过，将看到 准备安装 页面。点击 开始安装 以开始安装。

EIM 准备安装

EIM 准备安装

安装过程中，可以直接在界面中查看安装进度。

EIM 安装中

EIM 安装中

安装完成后，会出现 安装完成 页面。

EIM 安装完成

EIM 安装完成

如果安装失败，可以：

  • 点击界面底部的 日志 查看错误详情。解决问题后，点击 重试 重新开始安装。

  • 或者，使用 自定义安装。

备注

使用 EIM CLI 在线安装

运行以下命令，在非交互模式下使用默认设置安装最新稳定版本的 ESP-IDF：

eim install

如果运行上述命令时遇到问题，或者需要自定义安装路径、选择 ESP-IDF 版本或修改其他设置项，请启动交互式安装向导，并按照屏幕上的提示操作：

eim wizard

如果安装向导中没有想要安装的 ESP-IDF 版本，请运行以下命令来安装任意可选 版本。例如，要安装 ESP-IDF v5.4.2，请运行：

eim install -i v5.4.2

安装完成后，会在终端中看到以下消息：

2025-11-03T15:54:12.537993300+08:00 - INFO - Wizard result: %{r}
2025-11-03T15:54:12.544174+08:00 - INFO - Successfully installed IDF
2025-11-03T15:54:12.545913900+08:00 - INFO - Now you can start using IDF tools

备注

使用已有配置文件在线安装

安装 ESP-IDF 时，安装程序会自动将设置保存到安装目录下的 eim_config.toml 配置文件中。此配置文件可在其他电脑上重复使用，快速复现相同的安装环境。

如需使用现有 eim_config.toml 文件安装 ESP-IDF，请参阅 EIM 文档 > Configuration Files。

离线安装

EIM 的图形用户界面和命令行界面均支持离线安装。具体操作请参阅 EIM 文档 > Offline Installation。

后续步骤

至此，您已准备就绪，可以使用 ESP-IDF 开发 ESP-IDF 应用程序了。接下来，请继续阅读 构建首个项目 章节，学习如何构建和运行您的第一个应用程序。

此文档对您有帮助吗？