# 可下载的 ESP-IDF 工具

[English]

构建过程中，ESP-IDF 依赖许多工具，如交叉编译工具链、CMake 构建系统等。

如 快速入门 所述，若所需工具版本可用，首选使用当前操作系统的软件包管理器（如 apt、yum、brew 等）安装相关工具。例如，在 Linux 和 macOS 系统中，建议用 Linux 和 macOS 系统的软件包管理器安装 CMake。

但部分 ESP-IDF 的特定工具在操作系统软件包存储库中不可用，且不同版本的 ESP-IDF 需相应使用不同版本的工具运行。为解决以上两个问题，ESP-IDF 提供了一组脚本，可以下载和安装正确的工具版本，并设置相应运行环境。

下文中，这类可下载的工具简称为“工具”。除此类工具外，ESP-IDF 还使用以下工具：

- ESP-IDF 捆绑的 Python 脚本，如 `idf.py`

- 从 PyPI 安装的 Python 软件包

以下各小节介绍了可下载工具的安装方法，并提供了在不同平台上安装的工具列表。

备注

本文档面向需要自定义其安装过程的高级用户、希望了解安装过程的用户以及 ESP-IDF 开发人员。

要了解如何安装 ESP-IDF 工具，请参阅 快速入门。

## 工具元数据文件

各平台所需工具及工具版本列表存放在 tools/tools.json 文件中，tools/tools_schema.json 定义了该文件的模式。

在安装工具或设置环境变量时，tools/idf_tools.py 脚本将使用上述文件。

## 工具安装目录

`IDF_TOOLS_PATH` 环境变量指定下载及安装工具的位置。若未设置该变量，Linux 和 macOS 系统的默认下载安装位置为 `$HOME/.espressif`，Windows 系统的默认下载安装位置为 `%USER_PROFILE%\.espressif`。

在 `IDF_TOOLS_PATH` 目录下，工具安装脚本会创建以下子目录和文件：

- `dist` — 工具存档下载位置。

- `tools` — 工具解压缩位置。工具会解压缩到子目录 `tools/TOOL_NAME/VERSION/` 中，该操作支持同时安装不同版本的工具。

- `idf-env.json` — “目标 (target)”和“功能 (feature)”等用户安装选项均存储在此文件中。“目标”为选择需要安装和保持更新的工具的芯片目标；“功能”则决定应安装哪些 Python 软件包。有关用户安装选项的详情，请参阅下文。

- `python_env` — 与工具无关；虚拟 Python 环境安装在其子目录中。注意，设置 `IDF_PYTHON_ENV_PATH` 环境变量可以将 Python 环境目录放置到其他位置。

  - `idf_version.txt` — 位于 `python_env` 目录下每个特定 Python 环境的子目录中，记录了该 Python 环境所对应的 ESP-IDF 版本。版本信息的存储格式如 `5.3` ，表示 ESP-IDF 版本 `v5.3`。

- `espidf.constraints.*.txt` — 每个 ESP-IDF 版本都有的约束文件，包含 Python 包版本要求。

## GitHub 资源镜像

工具下载器下载的工具大多属于 GitHub 发布的资源，即在 GitHub 上伴随软件发布的文件。

如果无法访问 GitHub 下载或访问速度较慢，可以配置一个 GitHub 资源镜像。

要使用乐鑫下载服务器，请将环境变量 `IDF_GITHUB_ASSETS` 设置为 `dl.espressif.com/github_assets`，在国内下载时，也可设置为 `dl.espressif.cn/github_assets` 加快下载速度。安装过程中，当从 `github.com` 下载工具时，URL 将重写为使用乐鑫下载服务器。

只要 URL 与 `github.com` 的下载 URL 格式匹配，任何镜像服务器均可使用，安装过程中下载的 GitHub 资源 URL 将把 `https://github.com` 替换为 `https://${IDF_GITHUB_ASSETS}`。

备注

目前，乐鑫下载服务器不会镜像 GitHub 上的所有内容，只镜像部分发布版本的附件资源文件及源文件。

## `idf_tools.py` 脚本

ESP-IDF 随附的 tools/idf_tools.py 脚本具备以下功能：

- `install`：将工具下载到 `${IDF_TOOLS_PATH}/dist` 目录，并解压缩到 `${IDF_TOOLS_PATH}/tools/TOOL_NAME/VERSION`。

  `install` 命令接收 `TOOL_NAME` 或 `TOOL_NAME@VERSION` 格式的安装工具列表。如果给定参数 `all`，则会安装列表上的所有工具，包括必须项和可选项。如果没有给定参数，或给定参数为 `required`，则只安装必须项。

- `download`：与 `install` 类似，但不会解压缩工具。使用可选项 `--platform` 可下载特定平台的工具。

- `export`：列出使用已安装工具前应设置的环境变量。对多数工具而言，只需要设置环境变量 `PATH`，但也有些工具需要设置额外的环境变量。

  环境变量可以以 `shell` 或 `key-value` 格式列出，使用 `--format` 参数设置该选项。

  - `export` 可选参数：

    - `--unset`：该参数可用于创建语句，取消特定全局变量设置，使环境恢复到调用 `export.{sh/fish}` 前的状态。

    - `--add_paths_extras`：该参数将 `$PATH` 中与 ESP-IDF 相关的额外路径添加到 `${IDF_TOOLS_PATH}/esp-idf.json` 中，以保证在退出当前 ESP-IDF 环境时删除全局变量。例如，在运行 `export.{sh/fish}` 脚本时，如果在全局变量 `$PATH` 中添加了新的路径，在命令中添加该参数可以将这些新路径保存到 `${IDF_TOOLS_PATH}/esp-idf.json` 文件中。

  - `shell`：生成适合在 shell 中执行的输出，例如，在 Linux 和 macOS 上生成以下输出

        export PATH="/home/user/.espressif/tools/tool/v1.0.0/bin:$PATH"

    在 Windows 上生成以下输出

        set "PATH=C:\Users\user\.espressif\tools\v1.0.0\bin;%PATH%"

    备注

    当前不支持以 Powershell 格式导出环境变量，可以用 `key-value` 格式代替。

    如果 shell 支持，则该命令的输出可用于更新环境变量。例如

        eval $($IDF_PATH/tools/idf_tools.py export)

  - `key-value`：以 `VARIABLE=VALUE` 格式生成输出，以便其他脚本解析

        PATH=/home/user/.espressif/tools/tool/v1.0.0:$PATH

    注意，用于处理此输出的脚本必须对输出中的 `$VAR` 或 `%VAR%` 模式进行扩展，即解析成对应变量。

- `list`：列出已知的工具版本，并指示哪些版本已安装。

  以下选项可用于自定义输出。

  - `--outdated`：仅列出安装在 `IDF_TOOLS_PATH` 中的过时版本工具。

- `check`：检查每个工具是否在系统路径和 `IDF_TOOLS_PATH` 中可用。

- `install-python-env`：在 `${IDF_TOOLS_PATH}/python_env` 目录或直接在 `IDF_PYTHON_ENV_PATH` 环境变量设置的目录中创建 Python 虚拟环境，并在其中安装所需的 Python 软件包。若虚拟环境已存在，系统将根据 `espidf.constraints.*.txt` 文件中的约束条件，将环境内的软件包更新至最新兼容版本。

  - 参数 `--features` 为可选项，用于指定要添加或删除的功能列表，功能之间用逗号分隔。

    1. 该参数将删除以 `-` 开头的功能，添加以 `+` 开头或无符号标记的功能。例如，要删除功能 `XY`，示例语法为 `--features=-XY`；要添加功能 `XY`，示例语法为 `--features=+XY` 或 `--features=XY`。如果为同一功能同时提供了删除和添加选项，则不执行任何操作。

    2. 每个功能都必须有依赖文件。例如，只有当 `${IDF_PATH}/tools/requirements/requirements.XY.txt` 文件已存在，并包含要安装的 Python 包列表时，功能 `XY` 才有效。

    3. `core` 功能为必须项，确保 ESP-IDF 的核心功能，如控制台中的构建、烧录、监视器、调试等。

    4. 用户可选择任意数量的可选功能，已选功能列表存储在 `idf-env.json` 中。

    5. 依赖文件中存储了需要安装的 Python 包以及 `espidf.constraints.*.txt` 文件，该约束文件从 https://dl.espressif.com 下载，并存储在 `${IDF_TOOLS_PATH}` 目录，包含了针对特定 ESP-IDF 版本的安装包版本要求。

  备注

  可以通过使用 `--no-constraints` 参数或将环境变量 `IDF_PYTHON_CHECK_CONSTRAINTS` 设置为 `no`，禁用约束文件的下载和使用，但 并不建议此做法。

- `check-python-dependencies`：检查所有必需的 Python 包是否均已安装。该命令会对比检查由 `idf-env.json` 功能列表从 `${IDF_PATH}/tools/requirements/requirements.*.txt` 所选择的软件包与 `espidf.constraints.*.txt` 文件指定的软件包版本是否一致。

  备注

  约束文件可通过 `install-python-env` 命令下载。与 `install-python-env` 命令类似，可以通过使用 `--no-constraints` 参数或将环境变量 `IDF_PYTHON_CHECK_CONSTRAINTS` 设置为 `no`，禁止使用约束文件。

- `uninstall`：打印并删除当前 ESP-IDF 版本未使用的工具。

  - `--dry-run` 打印已安装但未使用的工具。

  - `--remove-archives` 删除过去下载的所有旧版本软件安装包。

## 安装脚本

ESP-IDF 的根目录中提供了针对不同 shell 的用户安装脚本，包括：

- `install.bat` 适用于 Windows 命令提示符

- `install.ps1` 适用于 Powershell

- `install.sh` 适用于 Bash

- `install.fish` 适用于 Fish

这些脚本除了下载和安装 `IDF_TOOLS_PATH` 中的工具外，还会准备一个 Python 虚拟环境，并在此虚拟环境中安装所需软件包。

为启用相应功能，这些脚本可以选择性地接受一组以逗号分隔的芯片目标列表及 `--enable-*` 参数，这类参数会传递给 `idf_tools.py` 脚本，并由该脚本将这类参数存储在 `idf-env.json` 中，从而逐步启用芯片目标及功能。

要为所有芯片目标安装工具，请在不使用任何可选参数的情况下，运行 `idf_tools.py install --targets=all`。要安装具备 ESP-IDF 核心功能的 Python 软件包，请运行 `idf_tools.py install-python-env --features=core`。

也可为特定芯片安装工具，例如，运行 `install.sh esp32` 可以只为 ESP32 安装工具。更多相关示例，请参阅 第三步：设置工具。

运行 `idf_tools.py install-python-env --features=core,XY`，`install.sh --enable-XY` 可以启用 `XY` 功能。

## 导出脚本

由于安装好的工具并非永久添加到用户或系统的 `PATH` 环境变量中，因此，要在命令行中使用这些工具，还需要额外步骤。以下脚本会修改当前 shell 的环境变量，从而使用正确版本的工具：

- `export.bat` 适用于 Windows 命令提示符

- `export.ps1` 适用于 Powershell

- `export.sh` 适用于 Bash

- `export.fish` 适用于 Fish

备注

在 Bash 中修改 shell 环境时，必须使用 `. ./export.sh` 命令加载 `export.sh`，注意添加前面的点和空格。

`export.sh` 可以在多种 shell 中使用，例如 bash、sh、zsh、dash 等。在使用 bash 或 zsh 时，可以在任何路径中直接运行（例如 `. ./<<some_path>>/export.sh`），这是因为它能够自动检测到 `IDF_PATH`。若使用其它 shell, 则必须在 ESP-IDF 路径中运行 (`. ./export.sh`)，才能正确找到 `IDF_PATH`。

### activate.py

环境设置由底层的 `tools/activate.py` 脚本处理。该脚本用于执行所有必要的准备和检查，并生成一个临时文件，之后供导出脚本使用。

`activate.py` 也可以作为独立命令运行。执行该脚本时，会启动一个新的子 shell 并加载 ESP-IDF 环境。使用 `exit` 命令可以退出子 shell，并退回至最初执行该脚本的父 shell。

此外，`activate.py` 脚本的具体行为可以通过各种选项进行修改，例如使用 `--shell` 选项可以生成特定的 ESP-IDF shell。若想了解更多有关可用选项的详细信息，请使用 `activate.py --help` 命令。

备注

在 Windows 系统中使用 `activate.py` 脚本时，应执行 `python activate.py` 命令。这可以确保脚本在当前终端窗口中运行，而不是启动一个立即关闭的新窗口。

## 其他安装方法

为适用于不同环境，ESP-IDF 提供了更多用户友好的 `idf_tools.py` 包装工具：

- ESP-IDF 安装管理器 支持下载和安装工具，其内部使用 `idf_tools.py` 实现功能。

- ESP-IDF Eclipse 插件 包括了一个用于设置工具的菜单项，该插件内部调用 `idf_tools.py`。

- VSCode ESP-IDF 扩展 提供了设置工具的入门流程。尽管此扩展包不依赖 `idf_tools.py`，但安装方法相同。

## 自定义安装

推荐用户使用上述方法安装 ESP-IDF 工具，但也可以选择其他方式来构建 ESP-IDF 应用程序。自定义安装时，用户需将所有必要的工具都安装在某个位置，并在 `PATH` 中定义，以保证 ESP-IDF 构建系统可用。

在进行自定义安装时，确保设置 `ESP_IDF_VERSION` 环境变量以反映当前的 ESP-IDF 版本，例如，使用 `5.3` 的格式表示 ESP-IDF 版本 `v5.3`。该变量是某些组件进行特定的版本配置时所必需的，通常在标准安装过程中由 `idf_tools.py export` 脚本设置。

## 卸载 ESP-IDF

卸载 ESP-IDF 需要删除安装过程中配置的工具和环境变量。

- 使用 ESP-IDF 安装管理器 的用户可以在图形用户界面 (GUI) 或命令行界面 (CLI) 中卸载 ESP-IDF。

- 工具安装目录 下包含了已下载及安装的工具，删除该目录即可删除此前通过运行 安装脚本 安装的内容。通过 导出脚本 设置的环境变量不具备永久性，新环境中不会存在此类环境变量。

- 如在安装过程中进行了自定义设置，除删除上述工具外，可能还涉及手动恢复此前为适用 ESP-IDF 工具而修改的环境变量及系统路径，例如 `IDF_PYTHON_ENV_PATH` 或 `IDF_TOOLS_PATH`。如存在通过手动复制安装的工具，则也需手动追踪并删除相关文件。

- 如安装了 ESP-IDF Eclipse 或 VSCode ESP-IDF 扩展程序 等插件，则需按照对应插件文档中的特定卸载说明进行操作。

备注

卸载 ESP-IDF 工具不会删除任何项目文件或用户代码。为防止意外丢失其他文件，请在删除文件时谨慎操作。如果对某个步骤的操作有所疑问，请参考前述安装说明。

上述卸载指南默认需卸载的工具是按本文档中的步骤进行安装的。如果使用了自定义安装，可能需要进行相应调整。

## ESP-IDF 工具列表

### xtensa-esp-elf-gdb

GDB for Xtensa

License: GPL-3.0-or-later

More info: https://github.com/espressif/binutils-gdb

Platform | Required | Download
--- | --- | ---
linux-amd64 | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/xtensa-esp-elf-gdb-17.1_20260402-x86_64-linux-gnu.tar.gz SHA256: 73bc6c4e50b06dceb60e94b53aded61b7769be3cf563572269d9c8d643db8e95
linux-arm64 | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/xtensa-esp-elf-gdb-17.1_20260402-aarch64-linux-gnu.tar.gz SHA256: 00290ffe21b2916ffd343fd28ac34fc8b93e99b992a3656fa09b4f2bdc564bea
linux-armel | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/xtensa-esp-elf-gdb-17.1_20260402-arm-linux-gnueabi.tar.gz SHA256: f187a315e0393c2086d47e22f092524e3a1026143daa93c8e2bbdb8eac77d488
linux-armhf | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/xtensa-esp-elf-gdb-17.1_20260402-arm-linux-gnueabihf.tar.gz SHA256: c0610a3e19f81cec5c7a9a8d7a3e8bfb53ff965c088ce0870c7df3180e78841b
linux-i686 | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/xtensa-esp-elf-gdb-17.1_20260402-i586-linux-gnu.tar.gz SHA256: 303b06d82d2802f508af603cd7a1e256dca0f232a2fa28ab9fa35539c2c858ac
macos | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/xtensa-esp-elf-gdb-17.1_20260402-x86_64-apple-darwin24.5.tar.gz SHA256: 706d58849fd4a83244023051605b3631e835565395fa2783ed5afce1f17413ee
macos-arm64 | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/xtensa-esp-elf-gdb-17.1_20260402-aarch64-apple-darwin24.5.tar.gz SHA256: da97440e74a9ff36370bdb598cf421a8183c11ae6fb44431be594ad16dbe77ef
win-arm64 | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/xtensa-esp-elf-gdb-17.1_20260402-aarch64-w64-mingw32.zip SHA256: 4ff247465d84030ab29b741874d16d740d12febc0508501b72b69564decb17e4
win32 | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/xtensa-esp-elf-gdb-17.1_20260402-i686-w64-mingw32.zip SHA256: 8125a724e4f25c22b19a0321bce8b6a8675e12e0d12e5757d2ed75bd7262c53c
win64 | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/xtensa-esp-elf-gdb-17.1_20260402-x86_64-w64-mingw32.zip SHA256: 7525ae46b39fc87568717d8f0cc3dfbcdb77b96435dd80acfce6918b0abc2b8a

### riscv32-esp-elf-gdb

GDB for RISC-V

License: GPL-3.0-or-later

More info: https://github.com/espressif/binutils-gdb

Platform | Required | Download
--- | --- | ---
linux-amd64 | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/riscv32-esp-elf-gdb-17.1_20260402-x86_64-linux-gnu.tar.gz SHA256: 35f3db841338cb4f9bc60d757bc3e87dfa50ff50607bcbc3867c5b1ac28dd342
linux-arm64 | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/riscv32-esp-elf-gdb-17.1_20260402-aarch64-linux-gnu.tar.gz SHA256: f185d924497750f254290a32c48163c08e3b2a29eb248d739d90990ebee17f44
linux-armel | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/riscv32-esp-elf-gdb-17.1_20260402-arm-linux-gnueabi.tar.gz SHA256: 88c8d492345eb972e5f978defb3395643303a18cf1870ce8cd9b8621d244b36e
linux-armhf | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/riscv32-esp-elf-gdb-17.1_20260402-arm-linux-gnueabihf.tar.gz SHA256: 739c145268a5b5d8eb90d56951cb7fae9dbb3a0c5eb22e20b837d295431f9635
linux-i686 | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/riscv32-esp-elf-gdb-17.1_20260402-i586-linux-gnu.tar.gz SHA256: 29efe15235157bee507d97787a03e569f073bfef254c75d9662ec7f6e5162066
macos | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/riscv32-esp-elf-gdb-17.1_20260402-x86_64-apple-darwin24.5.tar.gz SHA256: 4845ec4968207e40c9f840f29007d8e0cd7d11eb613bb9e9078a41bb0ceb6d4d
macos-arm64 | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/riscv32-esp-elf-gdb-17.1_20260402-aarch64-apple-darwin24.5.tar.gz SHA256: f944bb6a07b03e5d74dd1f878ba05320ee7957d3a06bcc80cd0a9cf355e8ceea
win-arm64 | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/riscv32-esp-elf-gdb-17.1_20260402-aarch64-w64-mingw32.zip SHA256: dd1715255b8e6334de20599cd9c2bbb2d1c9c443acafe76e9f0f792466731902
win32 | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/riscv32-esp-elf-gdb-17.1_20260402-i686-w64-mingw32.zip SHA256: 77b04d797b699127c7d395c55eef0d09840255e7710a0bd51bcbae83ffec1f0c
win64 | required | https://github.com/espressif/binutils-gdb/releases/download/esp-gdb-v17.1_20260402/riscv32-esp-elf-gdb-17.1_20260402-x86_64-w64-mingw32.zip SHA256: f9e56a0d17414a30f7c457f7804173ecfb078b90d94a7b9f6318dc9652575d3f

### xtensa-esp-elf

Toolchain for 32-bit Xtensa based on GCC

License: GPL-3.0-with-GCC-exception

More info: https://github.com/espressif/crosstool-NG

Platform | Required | Download
--- | --- | ---
linux-amd64 | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/xtensa-esp-elf-15.2.0_20251204-x86_64-linux-gnu.tar.xz SHA256: 3d50f5cd5f173acfd524e07c1cd69bc99585731a415ca2e5bce879997fe602b8
linux-arm64 | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/xtensa-esp-elf-15.2.0_20251204-aarch64-linux-gnu.tar.xz SHA256: c8a8255009803036ba3def98a97a7134ee5a8ac5db048425e126fcf07f27ce1c
linux-armel | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/xtensa-esp-elf-15.2.0_20251204-arm-linux-gnueabi.tar.xz SHA256: 0ae215a8adb2823b370e31d20891747af42b86ce5042331df50829942d8cbbfe
linux-armhf | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/xtensa-esp-elf-15.2.0_20251204-arm-linux-gnueabihf.tar.xz SHA256: 99c1b5d45e9d661457d7a98494e5ebb2ed2e01b4b4dd4861de750acaec15a7bc
linux-i686 | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/xtensa-esp-elf-15.2.0_20251204-i586-linux-gnu.tar.xz SHA256: 6d3c510ddf5f084734c1dd5671d87a7b13973d713f641596ec1351dcce8d3ff3
macos | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/xtensa-esp-elf-15.2.0_20251204-x86_64-apple-darwin.tar.xz SHA256: 96da1fcf01e2ac89819d1e336ca9e27762c35ea120627b89de8fd482f42c54f8
macos-arm64 | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/xtensa-esp-elf-15.2.0_20251204-aarch64-apple-darwin.tar.xz SHA256: 68d3fb1e75c6bb1b88c6a2c74977abd51efd09b560a99149bafdcf403cb21941
win32 | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/xtensa-esp-elf-15.2.0_20251204-i686-w64-mingw32.zip SHA256: 72403f48827f75495f7c0b1c2be9f643c8dac25af7722545fc3ba1f21e834389
win64 | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/xtensa-esp-elf-15.2.0_20251204-x86_64-w64-mingw32.zip SHA256: efa1e337b5f64239674bf755b767969cbba7f4e66fe7c6ab8d19b650f56012a9

### esp-clang

Toolchain for all Espressif chips based on clang

License: Apache-2.0

More info: https://github.com/espressif/llvm-project

Platform | Required | Download
--- | --- | ---
linux-amd64 | optional | https://github.com/espressif/llvm-project/releases/download/esp-20.1.1_20250829/clang-esp-20.1.1_20250829-x86_64-linux-gnu.tar.xz SHA256: 88910c21350c06a521f243304d1a3adbdb78447123b3f8e27493aab75e3cc07f
linux-arm64 | optional | https://github.com/espressif/llvm-project/releases/download/esp-20.1.1_20250829/clang-esp-20.1.1_20250829-aarch64-linux-gnu.tar.xz SHA256: 41f536fdee22527011d89e416b301648afd9f738d03e1c62f2b27e36ec395c4c
linux-armhf | optional | https://github.com/espressif/llvm-project/releases/download/esp-20.1.1_20250829/clang-esp-20.1.1_20250829-arm-linux-gnueabihf.tar.xz SHA256: 7b695e88e21ba8a503d504f940dd34a7e4d3e98605c856b6836eec9117a5be94
macos | optional | https://github.com/espressif/llvm-project/releases/download/esp-20.1.1_20250829/clang-esp-20.1.1_20250829-x86_64-apple-darwin.tar.xz SHA256: 7dca85cd594185d8f9cf76f7e0c3420ee07057c1538b0016d8342677463f9ade
macos-arm64 | optional | https://github.com/espressif/llvm-project/releases/download/esp-20.1.1_20250829/clang-esp-20.1.1_20250829-aarch64-apple-darwin.tar.xz SHA256: 85ff833a326593df376010a2aa18d6aa444f239c1dfed604e13502d00c19db30
win64 | optional | https://github.com/espressif/llvm-project/releases/download/esp-20.1.1_20250829/clang-esp-20.1.1_20250829-x86_64-w64-mingw32.tar.xz SHA256: f40d7fa0efa399d129b675585355a7ef42a3492188d743e8e089b6038fcc0da1

### esp-clang-libs

Standalone Clang shared libraries distribution

License: Apache-2.0

More info: https://github.com/espressif/llvm-project

Platform | Required | Download
--- | --- | ---
linux-amd64 | optional | https://github.com/espressif/llvm-project/releases/download/esp-20.1.1_20250829/libs-clang-esp-20.1.1_20250829-x86_64-linux-gnu.tar.xz SHA256: 0128e2a86b262e3edfce026034ede07e2f45732b10c6cb8ac522c8f4c72befd8
linux-arm64 | optional | https://github.com/espressif/llvm-project/releases/download/esp-20.1.1_20250829/libs-clang-esp-20.1.1_20250829-aarch64-linux-gnu.tar.xz SHA256: cca598861f999bfd408491f4288c2f381b448f9ddbdac2fb4144747329878405
linux-armhf | optional | https://github.com/espressif/llvm-project/releases/download/esp-20.1.1_20250829/libs-clang-esp-20.1.1_20250829-arm-linux-gnueabihf.tar.xz SHA256: 26251ee323f616199fcef7a8ea5ee95a2cda2c1e781196ec002c49aeb99de1db
macos | optional | https://github.com/espressif/llvm-project/releases/download/esp-20.1.1_20250829/libs-clang-esp-20.1.1_20250829-x86_64-apple-darwin.tar.xz SHA256: 1c8ad98599a58c64396476ae9f66e33f408a2b2ed8ee6f8b2f0a92a5bd6bad84
macos-arm64 | optional | https://github.com/espressif/llvm-project/releases/download/esp-20.1.1_20250829/libs-clang-esp-20.1.1_20250829-aarch64-apple-darwin.tar.xz SHA256: 9582374ed7664aa46c5fc8cedde74b81ec85db9013e7ce85d01e172e92f0ac1f
win64 | optional | https://github.com/espressif/llvm-project/releases/download/esp-20.1.1_20250829/libs-clang-esp-20.1.1_20250829-x86_64-w64-mingw32.tar.xz SHA256: f4346641a38e6a9adad79c429be506b3df26540c50f39ab49dba9ad2c797a805

### riscv32-esp-elf

Toolchain for 32-bit RISC-V based on GCC

License: GPL-3.0-with-GCC-exception

More info: https://github.com/espressif/crosstool-NG

Platform | Required | Download
--- | --- | ---
linux-amd64 | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/riscv32-esp-elf-15.2.0_20251204-x86_64-linux-gnu.tar.xz SHA256: ace5aae6afe98f754947be043d40173e2e22ace57754b11a394b7238eefa01cf
linux-arm64 | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/riscv32-esp-elf-15.2.0_20251204-aarch64-linux-gnu.tar.xz SHA256: 90cccb3ef035f016836dd7c292528b27333a716d42b9361a68005d178c0f70bf
linux-armel | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/riscv32-esp-elf-15.2.0_20251204-arm-linux-gnueabi.tar.xz SHA256: 5603d18a0534ab5c2faca672ac890ad5b57727e55c6734adf6584aa73844f112
linux-armhf | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/riscv32-esp-elf-15.2.0_20251204-arm-linux-gnueabihf.tar.xz SHA256: 61b2feebfe14c5f2a7966ccec0c1c7ed2e2840d260671730f376aa92323b1338
linux-i686 | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/riscv32-esp-elf-15.2.0_20251204-i586-linux-gnu.tar.xz SHA256: 8dc31a97c008bf80d0c0b20b5960c522d9552f77a79ffd60e3ae6b1329cd68ef
macos | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/riscv32-esp-elf-15.2.0_20251204-x86_64-apple-darwin.tar.xz SHA256: 6d4709eadf4c66aecb51c0ff9c7b068eefa6ecec37aa7817f172c9f735318e73
macos-arm64 | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/riscv32-esp-elf-15.2.0_20251204-aarch64-apple-darwin.tar.xz SHA256: 0869d1083532c631808543dd802885f02dbe1bb3bd640be0dee827e82ded768d
win32 | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/riscv32-esp-elf-15.2.0_20251204-i686-w64-mingw32.zip SHA256: a52d9c855f1771527d2a6b6a6012ddff3f17bb5c937830b163aa8418177c86da
win64 | required | https://github.com/espressif/crosstool-NG/releases/download/esp-15.2.0_20251204/riscv32-esp-elf-15.2.0_20251204-x86_64-w64-mingw32.zip SHA256: c61488aa15f49146aae918267110f775a52c3cef3844cbf261f475ef97523c3d

### esp32ulp-elf

Toolchain for ESP32 ULP coprocessor

License: GPL-3.0-or-later

More info: https://github.com/espressif/binutils-gdb

Platform | Required | Download
--- | --- | ---
linux-amd64 | required | https://github.com/espressif/binutils-gdb/releases/download/esp32ulp-elf-2.38_20240113/esp32ulp-elf-2.38_20240113-linux-amd64.tar.gz SHA256: d13a808365b78465fa6591636dfbbb9604d9d15a397c3d9cd22626d54828ac2c
linux-arm64 | required | https://github.com/espressif/binutils-gdb/releases/download/esp32ulp-elf-2.38_20240113/esp32ulp-elf-2.38_20240113-linux-arm64.tar.gz SHA256: ecce0788ce1000e5c669c5adaf2fd5bf7f9bf96dcdbd3555d1d9ce4dcb311038
linux-armel | required | https://github.com/espressif/binutils-gdb/releases/download/esp32ulp-elf-2.38_20240113/esp32ulp-elf-2.38_20240113-linux-armel.tar.gz SHA256: 7228b01277f7908d72eb659470f82e143c4c66b444538a464290d88ece16130e
linux-armhf | required | https://github.com/espressif/binutils-gdb/releases/download/esp32ulp-elf-2.38_20240113/esp32ulp-elf-2.38_20240113-linux-armhf.tar.gz SHA256: 951b089c66561bc2190a8d57c316dfaef985a778728a7c30e1edcd29fe180016
linux-i686 | required | https://github.com/espressif/binutils-gdb/releases/download/esp32ulp-elf-2.38_20240113/esp32ulp-elf-2.38_20240113-linux-i686.tar.gz SHA256: df323d40962313168f6feeb2d9471c6010ff23a7896f40244e62991517d9745b
macos | required | https://github.com/espressif/binutils-gdb/releases/download/esp32ulp-elf-2.38_20240113/esp32ulp-elf-2.38_20240113-macos.tar.gz SHA256: b2aeba8eaafdf156e9e30be928dde1f133b00eaf33802d96827ec544ac7c864c
macos-arm64 | required | https://github.com/espressif/binutils-gdb/releases/download/esp32ulp-elf-2.38_20240113/esp32ulp-elf-2.38_20240113-macos-arm64.tar.gz SHA256: e3a4dfea043e2bce8cd00b3a0b260a59249fa61ca5931bf02f18a3d43c18deb4
win32 | required | https://github.com/espressif/binutils-gdb/releases/download/esp32ulp-elf-2.38_20240113/esp32ulp-elf-2.38_20240113-win32.zip SHA256: d33b64f49df27dcfa4a24d3af1a5ead77b020f85f33448994c31b98f88e66bb4
win64 | required | https://github.com/espressif/binutils-gdb/releases/download/esp32ulp-elf-2.38_20240113/esp32ulp-elf-2.38_20240113-win64.zip SHA256: 3a7627008ac92d1580542b95c696449e56aaa1d0881dc3ef5fd5c60afc77a49d

### cmake

CMake build system

On Linux and macOS, it is recommended to install CMake using the OS-specific package manager (like apt, yum, brew, etc.). However, for convenience it is possible to install CMake using idf_tools.py along with the other tools.

License: BSD-3-Clause

More info: https://github.com/Kitware/CMake

Platform | Required | Download
--- | --- | ---
linux-amd64 | optional | https://github.com/Kitware/CMake/releases/download/v4.0.3/cmake-4.0.3-linux-x86_64.tar.gz SHA256: 585ae9e013107bc8e7c7c9ce872cbdcbdff569e675b07ef57aacfb88c886faac
linux-arm64 | optional | https://github.com/Kitware/CMake/releases/download/v4.0.3/cmake-4.0.3-linux-aarch64.tar.gz SHA256: 391da1544ef50ac31300841caaf11db4de3976cdc4468643272e44b3f4644713
linux-armel | optional | https://dl.espressif.com/dl/cmake/cmake-4.0.3-Linux-armv7l.tar.gz SHA256: ee80bd9c5a310928eb89c9d28c6867a497c9b146e271ede8383e31426b930e15
linux-armhf | optional | https://dl.espressif.com/dl/cmake/cmake-4.0.3-Linux-armv7l.tar.gz SHA256: ee80bd9c5a310928eb89c9d28c6867a497c9b146e271ede8383e31426b930e15
macos | optional | https://github.com/Kitware/CMake/releases/download/v4.0.3/cmake-4.0.3-macos-universal.tar.gz SHA256: 4e85de4daf1c3e82d7dc6b8ba5683972944b466343aeb9c327a742437bb3ce9a
macos-arm64 | optional | https://github.com/Kitware/CMake/releases/download/v4.0.3/cmake-4.0.3-macos-universal.tar.gz SHA256: 4e85de4daf1c3e82d7dc6b8ba5683972944b466343aeb9c327a742437bb3ce9a
win-arm64 | required | https://github.com/Kitware/CMake/releases/download/v4.0.3/cmake-4.0.3-windows-arm64.zip SHA256: 86ccd6485bbd4bb41a1a858db397be5bca5e0de96858bf8dbba7a64407bd6c00
win32 | required | https://github.com/Kitware/CMake/releases/download/v4.0.3/cmake-4.0.3-windows-x86_64.zip SHA256: b59a31dfbfa376a4aaea9ff560ff2b29f78ee5f9fb15447fc71ae7bf9fea9379
win64 | required | https://github.com/Kitware/CMake/releases/download/v4.0.3/cmake-4.0.3-windows-x86_64.zip SHA256: b59a31dfbfa376a4aaea9ff560ff2b29f78ee5f9fb15447fc71ae7bf9fea9379

### openocd-esp32

OpenOCD for ESP32

License: GPL-2.0-only

More info: https://github.com/espressif/openocd-esp32

Platform | Required | Download
--- | --- | ---
linux-amd64 | required | https://github.com/espressif/openocd-esp32/releases/download/v0.12.0-esp32-20260424/openocd-esp32-linux-amd64-0.12.0-esp32-20260424.tar.gz SHA256: 0c875beb0e8d89cee4335968e8a27c7d151f05b91f636263c81ab01e098d390d
linux-arm64 | required | https://github.com/espressif/openocd-esp32/releases/download/v0.12.0-esp32-20260424/openocd-esp32-linux-arm64-0.12.0-esp32-20260424.tar.gz SHA256: f1b87d408adf6f2eb08a2b067ff7de38310829cc952c0f5d1d09920b0200a6e4
linux-armel | required | https://github.com/espressif/openocd-esp32/releases/download/v0.12.0-esp32-20260424/openocd-esp32-linux-armel-0.12.0-esp32-20260424.tar.gz SHA256: 6d8d3aa1a4d77610e03cbba48e359c14e7e96f5b3e9d4dfc0b7d1a2846421ca4
linux-armhf | required | https://github.com/espressif/openocd-esp32/releases/download/v0.12.0-esp32-20260424/openocd-esp32-linux-armhf-0.12.0-esp32-20260424.tar.gz SHA256: e7ad3fdd0c17679480c8f2a1a834db6c06db1f10fa500143fb701f0b833e5f7f
macos | required | https://github.com/espressif/openocd-esp32/releases/download/v0.12.0-esp32-20260424/openocd-esp32-macos-0.12.0-esp32-20260424.tar.gz SHA256: f3e3008e6a85e4dfea0177b9ea3fd769447e19a0f132e7754e4a7db164727f8e
macos-arm64 | required | https://github.com/espressif/openocd-esp32/releases/download/v0.12.0-esp32-20260424/openocd-esp32-macos-arm64-0.12.0-esp32-20260424.tar.gz SHA256: c7bffa205ca92a69ae7bc74e6e428824084e404355cbb9df2238fe30f5f435bb
win32 | required | https://github.com/espressif/openocd-esp32/releases/download/v0.12.0-esp32-20260424/openocd-esp32-win32-0.12.0-esp32-20260424.zip SHA256: 51682616fb443819ba5b3d982d991917576ea24ab4b8b0c4ac7b6427c57d4d67
win64 | required | https://github.com/espressif/openocd-esp32/releases/download/v0.12.0-esp32-20260424/openocd-esp32-win64-0.12.0-esp32-20260424.zip SHA256: d0005eea5b916df047afca7b777792050f8c6a6a502407180c8d839e9a841f75

### ninja

Ninja build system

On Linux and macOS, it is recommended to install ninja using the OS-specific package manager (like apt, yum, brew, etc.). However, for convenience it is possible to install ninja using idf_tools.py along with the other tools.

License: Apache-2.0

More info: https://github.com/ninja-build/ninja

Platform | Required | Download
--- | --- | ---
linux-amd64 | optional | https://github.com/ninja-build/ninja/releases/download/v1.12.1/ninja-linux.zip SHA256: 6f98805688d19672bd699fbbfa2c2cf0fc054ac3df1f0e6a47664d963d530255
linux-arm64 | optional | https://github.com/ninja-build/ninja/releases/download/v1.12.1/ninja-linux-aarch64.zip SHA256: 5c25c6570b0155e95fce5918cb95f1ad9870df5768653afe128db822301a05a1
macos | optional | https://github.com/ninja-build/ninja/releases/download/v1.12.1/ninja-mac.zip SHA256: 89a287444b5b3e98f88a945afa50ce937b8ffd1dcc59c555ad9b1baf855298c9
macos-arm64 | optional | https://github.com/ninja-build/ninja/releases/download/v1.12.1/ninja-mac.zip SHA256: 89a287444b5b3e98f88a945afa50ce937b8ffd1dcc59c555ad9b1baf855298c9
win-arm64 | required | https://github.com/ninja-build/ninja/releases/download/v1.12.1/ninja-winarm64.zip SHA256: 79c96a50e0deafec212cfa85aa57c6b74003f52d9d1673ddcd1eab1c958c5900
win64 | required | https://github.com/ninja-build/ninja/releases/download/v1.12.1/ninja-win.zip SHA256: f550fec705b6d6ff58f2db3c374c2277a37691678d6aba463adcbb129108467a

### idf-exe

IDF wrapper tool for Windows

License: Apache-2.0

More info: https://github.com/espressif/idf_py_exe_tool

Platform | Required | Download
--- | --- | ---
win32 | required | https://github.com/espressif/idf_py_exe_tool/releases/download/v1.0.3/idf-exe-v1.0.3.zip SHA256: 7c81ef534c562354a5402ab6b90a6eb1cc8473a9f4a7b7a7f93ebbd23b4a2755
win64 | required | https://github.com/espressif/idf_py_exe_tool/releases/download/v1.0.3/idf-exe-v1.0.3.zip SHA256: 7c81ef534c562354a5402ab6b90a6eb1cc8473a9f4a7b7a7f93ebbd23b4a2755

### ccache

Ccache (compiler cache)

License: GPL-3.0-or-later

More info: https://github.com/ccache/ccache

Platform | Required | Download
--- | --- | ---
win64 | required | https://github.com/ccache/ccache/releases/download/v4.12.1/ccache-4.12.1-windows-x86_64.zip SHA256: 98aea520d66905b8ba7a8e648a4cc0ca941d5e119d441f1e879a4a9045bf18f6

### dfu-util

dfu-util (Device Firmware Upgrade Utilities)

License: GPL-2.0-only

More info: http://dfu-util.sourceforge.net/

Platform | Required | Download
--- | --- | ---
win64 | required | https://dl.espressif.com/dl/dfu-util-0.11-win64.zip SHA256: 652eb94cb1c074c6dbead9e47adb628922aeb198a4d440a346ab32e7a0e9bf64

### esp-rom-elfs

ESP ROM ELFs

License: Apache-2.0

More info: https://github.com/espressif/esp-rom-elfs

Platform | Required | Download
--- | --- | ---
any | required | https://github.com/espressif/esp-rom-elfs/releases/download/20241011/esp-rom-elfs-20241011.tar.gz SHA256: 921f000164a421c7628fbfee55b173384aafaa51883adc65cd27bf9b0af9e9a9

### qemu-xtensa

QEMU for Xtensa

Some ESP-specific instructions for running QEMU for Xtensa chips are here: https://github.com/espressif/esp-toolchain-docs/blob/main/qemu/esp32/README.md

License: GPL-2.0-only

More info: https://github.com/espressif/qemu

Platform | Required | Download
--- | --- | ---
linux-amd64 | optional | https://github.com/espressif/qemu/releases/download/esp-develop-9.2.2-20250817/qemu-xtensa-softmmu-esp_develop_9.2.2_20250817-x86_64-linux-gnu.tar.xz SHA256: 588bfaccd0f929650655d10a580f020c6ba9c131712d8fa519280081b8d126eb
linux-arm64 | optional | https://github.com/espressif/qemu/releases/download/esp-develop-9.2.2-20250817/qemu-xtensa-softmmu-esp_develop_9.2.2_20250817-aarch64-linux-gnu.tar.xz SHA256: 317f6e0fd1dba0886d8110709823d909593ef29438822a14f81ebe19d72ce7cd
macos | optional | https://github.com/espressif/qemu/releases/download/esp-develop-9.2.2-20250817/qemu-xtensa-softmmu-esp_develop_9.2.2_20250817-x86_64-apple-darwin.tar.xz SHA256: 00b9dbc2124cf7633cb86f264fbc524226ad4001bce68bbdba43c9bdc4eb026e
macos-arm64 | optional | https://github.com/espressif/qemu/releases/download/esp-develop-9.2.2-20250817/qemu-xtensa-softmmu-esp_develop_9.2.2_20250817-aarch64-apple-darwin.tar.xz SHA256: aa92e337461d482f5d9f31cd8efc0bd67b3de8fcfcfb567289cb43a59c184651
win64 | optional | https://github.com/espressif/qemu/releases/download/esp-develop-9.2.2-20250817/qemu-xtensa-softmmu-esp_develop_9.2.2_20250817-x86_64-w64-mingw32.tar.xz SHA256: ef550b912726997f3c1ff4a4fb13c1569e2b692efdc5c9f9c3c926a8f7c540fa

### qemu-riscv32

QEMU for RISC-V

Some ESP-specific instructions for running QEMU for RISC-V chips are here: https://github.com/espressif/esp-toolchain-docs/blob/main/qemu/esp32c3/README.md

License: GPL-2.0-only

More info: https://github.com/espressif/qemu

Platform | Required | Download
--- | --- | ---
linux-amd64 | optional | https://github.com/espressif/qemu/releases/download/esp-develop-9.2.2-20250817/qemu-riscv32-softmmu-esp_develop_9.2.2_20250817-x86_64-linux-gnu.tar.xz SHA256: 373b37a68bae3ef441ead24a7bfc950fcbfc274cbdd2b628fc6915f179eb1d8e
linux-arm64 | optional | https://github.com/espressif/qemu/releases/download/esp-develop-9.2.2-20250817/qemu-riscv32-softmmu-esp_develop_9.2.2_20250817-aarch64-linux-gnu.tar.xz SHA256: f907a54313058f8a9681d2f48257d518950ff98bcd5a319194b4bee7c10cf223
macos | optional | https://github.com/espressif/qemu/releases/download/esp-develop-9.2.2-20250817/qemu-riscv32-softmmu-esp_develop_9.2.2_20250817-x86_64-apple-darwin.tar.xz SHA256: 820028ee7cd2dd8fe8cd8ca5519ab6e792d15fea9367c4525cf63c0f707c0b1f
macos-arm64 | optional | https://github.com/espressif/qemu/releases/download/esp-develop-9.2.2-20250817/qemu-riscv32-softmmu-esp_develop_9.2.2_20250817-aarch64-apple-darwin.tar.xz SHA256: 234690b6fa7c1d5dfe3dbb2bdd0c2810755e7c98999a9f21c389a6046b7eb76d
win64 | optional | https://github.com/espressif/qemu/releases/download/esp-develop-9.2.2-20250817/qemu-riscv32-softmmu-esp_develop_9.2.2_20250817-x86_64-w64-mingw32.tar.xz SHA256: 9474015f24d27acb7516955ec932e5307226bd9d6652cdc870793ed36010ab73

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。