可下载的 ESP-IDF 工具
构建过程中，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 环境目录放置到其他位置。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 软件包。参数
--features为可选项，用于指定要添加或删除的功能列表，功能之间用逗号分隔。该参数将删除以
-开头的功能，添加以+开头或无符号标记的功能。例如，要删除功能XY，示例语法为--features=-XY；要添加功能XY，示例语法为--features=+XY或--features=XY。如果为同一功能同时提供了删除和添加选项，则不执行任何操作。每个功能都必须有依赖文件。例如，只有当
${IDF_PATH}/tools/requirements/requirements.XY.txt文件已存在，并包含要安装的 Python 包列表时，功能XY才有效。core功能为必须项，确保 ESP-IDF 的核心功能，如控制台中的构建、烧录、监视器、调试等。用户可选择任意数量的可选功能，已选功能列表存储在
idf-env.json中。依赖文件中存储了需要安装的 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适用于 Powershellinstall.sh适用于 Bashinstall.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适用于 Powershellexport.sh适用于 Bashexport.fish适用于 Fish
备注
在 Bash 中修改 shell 环境时，必须使用 . ./export.sh 命令加载 export.sh，注意添加前面的点和空格。
export.sh 可以在除了 Bash 外的其他 shell（如 zsh）中使用。但在这种情况下，必须在运行脚本前设置 IDF_PATH 环境变量。在 Bash 中使用时，脚本会从当前目录猜测 IDF_PATH 的值。
除了调用 idf_tools.py，这些脚本还会列出已经添加到 PATH 的目录。
其他安装方法
为适用于不同环境，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
卸载 ESP-IDF 需要删除安装过程中配置的工具和环境变量。
使用 Windows ESP-IDF 工具安装器 的 Windows 用户可以直接运行卸载向导卸载 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
riscv32-esp-elf-gdb
GDB for RISC-V
License: GPL-3.0-or-later
More info: https://github.com/espressif/binutils-gdb
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
esp-clang
Toolchain for all Espressif chips based on clang
License: Apache-2.0
More info: https://github.com/espressif/llvm-project
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
esp32ulp-elf
Toolchain for ESP32 ULP coprocessor
License: GPL-3.0-or-later
More info: https://github.com/espressif/binutils-gdb
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/v3.24.0/cmake-3.24.0-linux-x86_64.tar.gz SHA256: 726f88e6598523911e4bce9b059dc20b851aa77f97e4cc5573f4e42775a5c16f |
| linux-arm64 | optional | https://github.com/Kitware/CMake/releases/download/v3.24.0/cmake-3.24.0-linux-aarch64.tar.gz SHA256: 50c3b8e9d3a3cde850dd1ea143df9d1ae546cbc5e74dc6d223eefc1979189651 |
| linux-armel | optional | https://dl.espressif.com/dl/cmake/cmake-3.24.0-Linux-armv7l.tar.gz SHA256: 7dc787ef968dfef92491a4f191b8739ff70f8a649608b811c7a737b52481beb0 |
| linux-armhf | optional | https://dl.espressif.com/dl/cmake/cmake-3.24.0-Linux-armv7l.tar.gz SHA256: 7dc787ef968dfef92491a4f191b8739ff70f8a649608b811c7a737b52481beb0 |
| macos | optional | https://github.com/Kitware/CMake/releases/download/v3.24.0/cmake-3.24.0-macos-universal.tar.gz SHA256: 3e0cca74a56d9027dabb845a5a26e42ef8e8b33beb1655d6a724187a345145e4 |
| macos-arm64 | optional | https://github.com/Kitware/CMake/releases/download/v3.24.0/cmake-3.24.0-macos-universal.tar.gz SHA256: 3e0cca74a56d9027dabb845a5a26e42ef8e8b33beb1655d6a724187a345145e4 |
| win32 | required | https://github.com/Kitware/CMake/releases/download/v3.24.0/cmake-3.24.0-windows-x86_64.zip SHA256: b1ad8c2dbf0778e3efcc9fd61cd4a962e5c1af40aabdebee3d5074bcff2e103c |
| win64 | required | https://github.com/Kitware/CMake/releases/download/v3.24.0/cmake-3.24.0-windows-x86_64.zip SHA256: b1ad8c2dbf0778e3efcc9fd61cd4a962e5c1af40aabdebee3d5074bcff2e103c |
openocd-esp32
OpenOCD for ESP32
License: GPL-2.0-only
More info: https://github.com/espressif/openocd-esp32
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.11.1/ninja-linux.zip SHA256: b901ba96e486dce377f9a070ed4ef3f79deb45f4ffe2938f8e7ddc69cfb3df77 |
| macos | optional | https://github.com/ninja-build/ninja/releases/download/v1.11.1/ninja-mac.zip SHA256: 482ecb23c59ae3d4f158029112de172dd96bb0e97549c4b1ca32d8fad11f873e |
| macos-arm64 | optional | https://github.com/ninja-build/ninja/releases/download/v1.11.1/ninja-mac.zip SHA256: 482ecb23c59ae3d4f158029112de172dd96bb0e97549c4b1ca32d8fad11f873e |
| win64 | required | https://github.com/ninja-build/ninja/releases/download/v1.11.1/ninja-win.zip SHA256: 524b344a1a9a55005eaf868d991e090ab8ce07fa109f1820d40e74642e289abc |
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.8/ccache-4.8-windows-x86_64.zip SHA256: a2b3bab4bb8318ffc5b3e4074dc25636258bc7e4b51261f7d9bef8127fda8309 |
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/20230320/esp-rom-elfs-20230320.tar.gz SHA256: 24bcc8cb3287175d4a0bfd65e04bf7ef592a10f022acffca0d5e87eee05996d4 |
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
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