ESP-IDF build process relies on a number of tools: cross-compiler toolchains, CMake build system, and others.

Installing the tools using an OS-specific package manager (like apt, yum, brew, etc.) is the preferred method when the required version of the tool is available. This recommendation is reflected in the Getting Started guide. For example, on Linux and macOS it is recommended to install CMake using an OS package manager.

However, some of the tools are IDF-specific and are not available in OS package repositories. Furthermore, different versions of ESP-IDF require different versions of the tools to operate correctly. To solve these two problems, ESP-IDF provides a set of scripts for downloading and installing the correct versions of tools, and exposing them in the environment.

The rest of the document refers to these downloadable tools simply as “tools”. Other kinds of tools used in ESP-IDF are:

• Python scripts bundled with ESP-IDF (such as idf.py)

• Python packages installed from PyPI.

The following sections explain the installation method, and provide the list of tools installed on each platform.

This document is provided for advanced users who need to customize their installation, users who wish to understand the installation process, and ESP-IDF developers.

If you are looking for instructions on how to install the tools, see the Getting Started Guide.

The list of tools and tool versions required for each platform is located in tools/tools.json. The schema of this file is defined by tools/tools_schema.json.

This file is used by tools/idf_tools.py script when installing the tools or setting up the environment variables.

## Tools installation directory¶

IDF_TOOLS_PATH environment variable specifies the location where the tools are to be downloaded and installed. If not set, IDF_TOOLS_PATH defaults to HOME/.espressif on Linux and macOS, and %USER_PROFILE%\.espressif on Windows.

Inside IDF_TOOLS_PATH, the scripts performing tools installation create the following directories:

• tools — where the tools are extracted. The tools are extracted into subdirectories: tools/TOOL_NAME/VERSION/. This arrangement allows different versions of tools to be installed side by side.

## GitHub Assets Mirror¶

Most of the tools downloaded by the tools installer are GitHub Release Assets, which are files attached to a software release on GitHub.

If GitHub downloads are inaccessible or slow to access, it’s possible to configure a GitHub assets mirror.

Any mirror server can be used provided the URL matches the github.com download URL format: the install process will replace https://github.com with https://${IDF_GITHUB_ASSETS} for any GitHub asset URL that it downloads. 注解 The Espressif download server doesn’t currently mirror everything from GitHub, it only mirrors files attached as Assets to some releases as well as source archives for some releases. ## idf_tools.py script¶ tools/idf_tools.py script bundled with ESP-IDF performs several functions: • install: Download the tool into${IDF_TOOLS_PATH}/dist directory, extract it into ${IDF_TOOLS_PATH}/tools/TOOL_NAME/VERSION. install command accepts the list of tools to install, in TOOL_NAME or TOOL_NAME@VERSION format. If all is given, all the tools (required and optional ones) are installed. If no argument or required is given, only the required tools are installed. • download: Similar to install but doesn’t extract the tools. An optional --platform argument may be used to download the tools for the specific platform. • export: Lists the environment variables which need to be set to use the installed tools. For most of the tools, setting PATH environment variable is sufficient, but some tools require extra environment variables. The environment variables can be listed in either of shell or key-value formats, set by --format parameter: • shell produces output suitable for evaluation in the shell. For example, export PATH="/home/user/.espressif/tools/tool/v1.0.0/bin:$PATH"

on Linux and macOS, and

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

on Windows.

注解

Exporting environment variables in Powershell format is not supported at the moment. key-value format may be used instead.

The output of this command may be used to update the environment variables, if the shell supports this. For example:

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

• key-value produces output in VARIABLE=VALUE format, suitable for parsing by other scripts:

PATH=/home/user/.espressif/tools/tool/v1.0.0:$PATH Note that the script consuming this output has to perform expansion of$VAR or %VAR% patterns found in the output.

• list: Lists the known versions of the tools, and indicates which ones are installed.

• check: For each tool, checks whether the tool is available in the system path and in IDF_TOOLS_PATH.

## Install scripts¶

Shell-specific user-facing scripts are provided in the root of ESP-IDF repository to facilitate tools installation. These are:

• install.bat for Windows Command Prompt

• install.ps1 for Powershell

• install.sh for Bash

Aside from downloading and installing the tools into IDF_TOOLS_PATH, these scripts prepare a Python virtual environment, and install the required packages into that environment.

## Export scripts¶

Since the installed tools are not permanently added into the user or system PATH environment variable, an extra step is required to use them in the command line. The following scripts modify the environment variables in the current shell to make the correct versions of the tools available:

• export.bat for Windows Command Prompt

• export.ps1 for Powershell

• export.sh for Bash

To modify the shell environment in Bash, export.sh must be “sourced”: . ./export.sh (note the leading dot and space).

export.sh may be used with shells other than Bash (such as zsh). However in this case the IDF_PATH environment variable must be set before running the script. When used in Bash, the script will guess the IDF_PATH value from its own location.

In addition to calling idf_tools.py, these scripts list the directories which have been added to the PATH.

## Other installation methods¶

Depending on the environment, more user-friendly wrappers for idf_tools.py are provided:

• IDF Tools installer for Windows can download and install the tools. Internally the installer uses idf_tools.py.

• Eclipse plugin for ESP-IDF includes a menu item to set up the tools. Internally the plugin calls idf_tools.py.

• Visual Studio Code extension for ESP-IDF includes an onboarding flow. This flow helps setting up the tools. Although the extension does not rely on idf_tools.py, the same installation method is used.

## Custom installation¶

Although the methods above are recommended for ESP-IDF users, they are not a must for building ESP-IDF applications. ESP-IDF build system expects that all the necessary tools are installed somewhere, and made available in the PATH.

## List of IDF Tools¶

### xtensa-esp32-elf¶

Toolchain for Xtensa (ESP32) based on GCC

Platform

Required

linux-amd64

required

SHA256: 44a0b467b9d2b759ab48b2f27aed684581f33c96e2842992781c4e045992c5b0

linux-armel

required

SHA256: fdacdb2a7bbf6293bcafda9b52463a4da8a2f3b7e1df9f83d35ff9d1efa22012

linux-i686

required

SHA256: e2024096492dfaa50fc6ac336cd8faa2e395e8cebb617753eab0b5f16d3dd0dc

macos

required

win32

required

SHA256: e4f9fdda192abfc9807e3e7fcd6e9fea30c1a0cf3f3c5a5c961b5114fc8c9b7e

win64

required

SHA256: f28f525f6554d72fcd60bdc67b6f095d6c022df6036c3c3166dace37d6ea10b3

### xtensa-esp32s2-elf¶

Toolchain for Xtensa (ESP32-S2) based on GCC

Platform

Required

linux-amd64

required

SHA256: b127baccfe6949ee7eaf3d0782ea772750a9b8e2732b16ce6bcc9dcd91f7209a

linux-armel

required

SHA256: 7ca0d240f11e1c53c01a56257b0c968f876ab405142d1068d8c9b456d939554c

linux-i686

required

SHA256: 9941f993ff84d1c606b45ffbeeb7bcdc5a72cf24e787bb9230390510fe3511c6

macos

required

SHA256: 4b55b1a9ca7fc945be6fc3513802b6cece9264bee4cbca76013569cec2695973

win32

required

SHA256: c94ec1e45c81b7e4944d216bab4aa41d46849768d7761fd691661dab1a3df828

win64

required

SHA256: 2a2a04e45a7dfe93356a2329162f7d013f06e3125fd7fc08a50e3bd5f4110300

### xtensa-esp32s3-elf¶

Toolchain for Xtensa (ESP32-S3) based on GCC

Platform

Required

linux-amd64

required

linux-armel

required

SHA256: 5108571286f8403cc06d951efdfa20e36ace9ee37bc19892cc1c04b52cc2fe83

linux-i686

required

SHA256: dc126b60f4492689d675f66a60a74c63e80ac5fbb345cf541c323a0a2592541d

macos

required

SHA256: 0887e2ff3ac20d36f6754e4f27a5e888b48db603e1026859f257f466e2569824

win32

required

SHA256: 6fb1e5b6f9606052af545176616441e00fdff64314a97b29ce349f28e5bfbab3

win64

required

### riscv32-esp-elf¶

Toolchain for 32-bit RISC-V based on GCC

Platform

Required

linux-amd64

required

SHA256: 3459618f33bbd5f54d7d7783e807cb6eef6472a220f2f1eb3faced735b9d13bb

linux-armel

required

SHA256: 24b9e54b348bbd5fb816fc4c52abb47337c702beecdbba840750b7cfb9d38069

linux-i686

required

SHA256: 954d340ebffef12a2ce9be1ea004e6f45a8863f1e6f41f46fd3f04f58499627c

macos

required

SHA256: 612fb3a3f84f703222327bd16581df8f80fda8cdf137637fe5d611587d1b664e

win32

required

SHA256: 527f5f258c28a1fce6264a4f8dcb63fbfbd1e810881783497eccd101ca38cb07

win64

required

SHA256: 8e8e3e385833960762e9f007bc3f7785daf282deb0c8a4dfdd6340b2cce556b0

### esp32ulp-elf¶

Toolchain for ESP32 ULP coprocessor

Platform

Required

linux-amd64

required

linux-armel

required

SHA256: 88967c086a6e71834282d9ae05841ee74dae1815f27807b25cdd3f7775a47101

macos

required

SHA256: a35d9e7a0445247c7fc9dccd3fbc35682f0fafc28beeb10c94b59466317190c4

win32

required

win64

required

### esp32s2ulp-elf¶

Toolchain for ESP32-S2 ULP coprocessor

Platform

Required

linux-amd64

required

SHA256: df7b2ff6c7c718a7cbe3b4b6dbcd68180d835d164d1913bc4698fd3781b9a466

linux-armel

required

SHA256: 893b213c8f716d455a6efb2b08b6cf1bc34d08b78ee19c31e82ac44b1b45417e

macos

required

SHA256: 5a9bb678a5246638cbda303f523d9bb8121a9a24dc01ecb22c21c46c41184155

win32

required

SHA256: 587de59fbb469a39f96168ae3eaa9f06b2601e6e0543c87eaf1bd97f23e5c4ca

win64

required

SHA256: 587de59fbb469a39f96168ae3eaa9f06b2601e6e0543c87eaf1bd97f23e5c4ca

### cmake¶

CMake build system

On Linux and macOS, it is recommended to install CMake using the OS package manager. However, for convenience it is possible to install CMake using idf_tools.py along with the other tools.

Platform

Required

linux-amd64

optional

SHA256: 12a577aa04b6639766ae908f33cf70baefc11ac4499b8b1c8812d99f05fb6a02

macos

optional

SHA256: f60e0ef96da48725cd8da7d6abe83cd9501167aa51625c90dd4d31081a631279

win32

required

SHA256: f37963bcfcebdfe5864926a3623f6c21220c35790c39cd65e64bd521cbb39c55

win64

required

SHA256: f37963bcfcebdfe5864926a3623f6c21220c35790c39cd65e64bd521cbb39c55

### openocd-esp32¶

OpenOCD for ESP32

Platform

Required

linux-amd64

required

SHA256: 0973c2503909af3e430b7a2309b6162ca375671ab2b22e37cba5159eea142139

linux-armel

required

SHA256: 3703401322cc51f85cb44e3a14a788fdc45883051eac3428b4d7bdf323dee2c7

macos

required

SHA256: cb9e8d486197fc6e8080fde089fa3e92770f8c7af01971a57d4ca9b424264b63

win32

required

SHA256: 931bc4c4587e0713d4fc4fbc81b9a79c8228268e61fcd14b2bdcb2f8bd519ef9

win64

required

SHA256: 931bc4c4587e0713d4fc4fbc81b9a79c8228268e61fcd14b2bdcb2f8bd519ef9

### ninja¶

Ninja build system

On Linux and macOS, it is recommended to install ninja using the OS package manager. However, for convenience it is possible to install ninja using idf_tools.py along with the other tools.

Platform

Required

linux-amd64

optional

https://dl.espressif.com/dl/ninja-1.10.2-linux64.tar.gz

SHA256: 32bb769de4d57aa7ee0e292cfcb7553e7cc8ea0961f7aa2b3aee60aa407c4033

macos

optional

https://dl.espressif.com/dl/ninja-1.10.2-osx.tar.gz

SHA256: 847bb1ca4bc16d8dba6aeed3ecb5055498b86bc68c364c37583eb5738bb440f1

win64

required

https://dl.espressif.com/dl/ninja-1.10.2-win64.zip

SHA256: bbde850d247d2737c5764c927d1071cbb1f1957dcabda4a130fa8547c12c695f

### idf-exe¶

IDF wrapper tool for Windows

Platform

Required

win32

required

https://dl.espressif.com/dl/idf-exe-v1.0.1.zip

SHA256: 53eb6aaaf034cc7ed1a97d5c577afa0f99815b7793905e9408e74012d357d04a

win64

required

https://dl.espressif.com/dl/idf-exe-v1.0.1.zip

SHA256: 53eb6aaaf034cc7ed1a97d5c577afa0f99815b7793905e9408e74012d357d04a

### ccache¶

Ccache (compiler cache)

Platform

Required

win64

required

https://dl.espressif.com/dl/ccache-3.7-w64.zip

SHA256: 37e833f3f354f1145503533e776c1bd44ec2e77ff8a2476a1d2039b0b10c78d6

Platform

Required