Downloadable Tools

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.

Note

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.

Tools metadata file

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:

  • dist — where the archives of the tools are downloaded.
  • 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.

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.

      Note

      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

Note

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

License: GPL-3.0-with-GCC-exception

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

Platform Required Download
linux-amd64 required

https://dl.espressif.com/dl/xtensa-esp32-elf-gcc8_2_0-esp-2019r2-linux-amd64.tar.gz

SHA256: e6d47c1dbd8c8cbfe37271e5e2aac53ee88c9e347ae937e22bf0c73f530efbdf

linux-armel required

https://dl.espressif.com/dl/xtensa-esp32-elf-gcc8_2_0-esp-2019r2-linux-armel.tar.gz

SHA256: 54a199c28f591da2466b21741911bc2ba77ddf82d3d2b66c6ce03c1a0c6835f0

linux-i686 required

https://dl.espressif.com/dl/xtensa-esp32-elf-gcc8_2_0-esp-2019r2-linux-i686.tar.gz

SHA256: 36a9648c414dbd1c518c687ce5587d9f8eaa94324f45d92e9ec31a1433a04df8

macos required

https://dl.espressif.com/dl/xtensa-esp32-elf-gcc8_2_0-esp-2019r2-macos.tar.gz

SHA256: dc62be8dd16c6d9d28d64e2b3f831fa208f3548c2ca73cdbcbdf68f474d59521

win32 required

https://dl.espressif.com/dl/xtensa-esp32-elf-gcc8_2_0-esp-2019r2-win32.zip

SHA256: c9d5776a22516f0825a7c68d835ffacc2392f913136893b7646e1288937cc65e

win64 required

https://dl.espressif.com/dl/xtensa-esp32-elf-gcc8_2_0-esp-2019r2-win32.zip

SHA256: c9d5776a22516f0825a7c68d835ffacc2392f913136893b7646e1288937cc65e

xtensa-esp32s2-elf

Toolchain for Xtensa (ESP32-S2) 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://dl.espressif.com/dl/xtensa-esp32s2-elf-gcc8_2_0-esp-2019r2-linux-amd64.tar.gz

SHA256: 59c6951e39937b9dfa53cca6d7707984ee39572071e56d11069f032d079477f5

linux-armel required

https://dl.espressif.com/dl/xtensa-esp32s2-elf-gcc8_2_0-esp-2019r2-linux-armel.tar.gz

SHA256: 92d80cf640db34913b91c1d8dae1632a7f5a740b5dcf39a3bea750b5dba05caa

linux-i686 required

https://dl.espressif.com/dl/xtensa-esp32s2-elf-gcc8_2_0-esp-2019r2-linux-i686.tar.gz

SHA256: d31c39dce8e6faa36807152a8afa8fe79d491bc551ad27dff1fed2f31dd6a39e

macos required

https://dl.espressif.com/dl/xtensa-esp32s2-elf-gcc8_2_0-esp-2019r2-macos.tar.gz

SHA256: 01f6d9b6d25a550975a16d2634a577a0c0f3c3c24db10edd1b714f9c192f490d

win32 required

https://dl.espressif.com/dl/xtensa-esp32s2-elf-gcc8_2_0-esp-2019r2-win32.zip

SHA256: f9b69732bd4e90d4558547f6a2d33f78433971e9e4f04968515cf460ea6de79a

win64 required

https://dl.espressif.com/dl/xtensa-esp32s2-elf-gcc8_2_0-esp-2019r2-win32.zip

SHA256: f9b69732bd4e90d4558547f6a2d33f78433971e9e4f04968515cf460ea6de79a

esp32ulp-elf

Toolchain for ESP32 ULP coprocessor

License: GPL-2.0-or-later

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

Platform Required Download
linux-amd64 required

https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32ulp-linux-amd64-2.28.51-esp-20191205.tar.gz

SHA256: 3016c4fc551181175bd9979869bc1d1f28fa8efa25a0e29ad7f833fca4bc03d7

linux-armel required

https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32ulp-linux-armel-2.28.51-esp-20191205.tar.gz

SHA256: 88967c086a6e71834282d9ae05841ee74dae1815f27807b25cdd3f7775a47101

macos required

https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32ulp-macos-2.28.51-esp-20191205.tar.gz

SHA256: a35d9e7a0445247c7fc9dccd3fbc35682f0fafc28beeb10c94b59466317190c4

win32 required

https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32ulp-win32-2.28.51-esp-20191205.zip

SHA256: bade309353a9f0a4e5cc03bfe84845e33205f05502c4b199195e871ded271ab5

win64 required

https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32ulp-win32-2.28.51-esp-20191205.zip

SHA256: bade309353a9f0a4e5cc03bfe84845e33205f05502c4b199195e871ded271ab5

esp32s2ulp-elf

Toolchain for ESP32-S2 ULP coprocessor

License: GPL-2.0-or-later

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

Platform Required Download
linux-amd64 required

https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32s2ulp-linux-amd64-2.28.51-esp-20191205.tar.gz

SHA256: df7b2ff6c7c718a7cbe3b4b6dbcd68180d835d164d1913bc4698fd3781b9a466

linux-armel required

https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32s2ulp-linux-armel-2.28.51-esp-20191205.tar.gz

SHA256: 893b213c8f716d455a6efb2b08b6cf1bc34d08b78ee19c31e82ac44b1b45417e

macos required

https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32s2ulp-macos-2.28.51-esp-20191205.tar.gz

SHA256: 5a9bb678a5246638cbda303f523d9bb8121a9a24dc01ecb22c21c46c41184155

win32 required

https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32s2ulp-win32-2.28.51-esp-20191205.zip

SHA256: 587de59fbb469a39f96168ae3eaa9f06b2601e6e0543c87eaf1bd97f23e5c4ca

win64 required

https://github.com/espressif/binutils-esp32ulp/releases/download/v2.28.51-esp-20191205/binutils-esp32s2ulp-win32-2.28.51-esp-20191205.zip

SHA256: 587de59fbb469a39f96168ae3eaa9f06b2601e6e0543c87eaf1bd97f23e5c4ca

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.13.4/cmake-3.13.4-Linux-x86_64.tar.gz

SHA256: 563a39e0a7c7368f81bfa1c3aff8b590a0617cdfe51177ddc808f66cc0866c76

macos optional

https://github.com/Kitware/CMake/releases/download/v3.13.4/cmake-3.13.4-Darwin-x86_64.tar.gz

SHA256: fef537614d73fda848f6168273b6c7ba45f850484533361e7bc50ac1d315f780

win32 required

https://github.com/Kitware/CMake/releases/download/v3.13.4/cmake-3.13.4-win32-x86.zip

SHA256: 28daf772f55d817a13ef14e25af2a5569f8326dac66a6aa3cc5208cf1f8e943f

win64 required

https://github.com/Kitware/CMake/releases/download/v3.13.4/cmake-3.13.4-win64-x64.zip

SHA256: bcd477d49e4a9400b41213d53450b474beaedb264631693c958ef9affa8e5623

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.10.0-esp32-20191114/openocd-esp32-linux64-0.10.0-esp32-20191114.tar.gz

SHA256: 978213e8345dd19762c79d4bda309331bb78db3d2a7f7193641dfcc978f6e5e5

linux-armel required

https://github.com/espressif/openocd-esp32/releases/download/v0.10.0-esp32-20191114/openocd-esp32-armel-0.10.0-esp32-20191114.tar.gz

SHA256: 3b41d889e54c03d26ebf4423084a1c25a9b0a8c5d93359a3eece1754377dbd81

macos required

https://github.com/espressif/openocd-esp32/releases/download/v0.10.0-esp32-20191114/openocd-esp32-macos-0.10.0-esp32-20191114.tar.gz

SHA256: 75ca2e235c35157d6dad2106cc62210ccb99b736da6940179aa1644fe1ae8c2b

win32 required

https://github.com/espressif/openocd-esp32/releases/download/v0.10.0-esp32-20191114/openocd-esp32-win32-0.10.0-esp32-20191114.zip

SHA256: 698bfa5903c99e2ee0a1898379b3a40451fcecbc1fd4fde4f2f1494e5725e7ab

win64 required

https://github.com/espressif/openocd-esp32/releases/download/v0.10.0-esp32-20191114/openocd-esp32-win32-0.10.0-esp32-20191114.zip

SHA256: 698bfa5903c99e2ee0a1898379b3a40451fcecbc1fd4fde4f2f1494e5725e7ab

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://dl.espressif.com/dl/ninja-1.9.0-linux64.tar.gz

SHA256: 978fd9e26c2db8d33392c6daef50e9edac0a3db6680710a9f9ad47e01f3e49b7

macos optional

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

SHA256: 9504cd1783ef3c242d06330a50d54dc8f838b605f5fc3e892c47254929f7350c

win64 required

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

SHA256: 2d70010633ddaacc3af4ffbd21e22fae90d158674a09e132e06424ba3ab036e9

idf-exe

IDF wrapper tool for Windows

License: Apache-2.0

More info: tools/windows/idf_exe

Platform Required Download
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)

License: GPL-3.0-or-later

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

Platform Required Download
win64 required

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

SHA256: 37e833f3f354f1145503533e776c1bd44ec2e77ff8a2476a1d2039b0b10c78d6