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.

注解

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.

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.

To use Espressif’s download server, set the environment variable IDF_GITHUB_ASSETS to dl.espressif.com/github_assets. When the install process is downloading a tool from github.com, the URL will be rewritten to use this server instead.

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

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-2020r3/xtensa-esp32-elf-gcc8_4_0-esp-2020r3-linux-amd64.tar.gz

SHA256: 674080a12f9c5ebe5a3a5ce51c6deaeffe6dfb06d6416233df86f25b574e9279

linux-armel

required

https://github.com/espressif/crosstool-NG/releases/download/esp-2020r3/xtensa-esp32-elf-gcc8_4_0-esp-2020r3-linux-armel.tar.gz

SHA256: 6771e011dffa2438ef84ff3474538b4a69df8f9d4cfae3b3707ca31c782ed7db

linux-i686

required

https://github.com/espressif/crosstool-NG/releases/download/esp-2020r3/xtensa-esp32-elf-gcc8_4_0-esp-2020r3-linux-i686.tar.gz

SHA256: 076b7e05304e26aa6ec105c9e0dc74addca079bc2cae6e42ee7575c5ded29877

macos

required

https://github.com/espressif/crosstool-NG/releases/download/esp-2020r3/xtensa-esp32-elf-gcc8_4_0-esp-2020r3-macos.tar.gz

SHA256: 6845f786303b26c4a55ede57487ba65bd25737232fe6104be03f25bb62f4631c

win32

required

https://github.com/espressif/crosstool-NG/releases/download/esp-2020r3/xtensa-esp32-elf-gcc8_4_0-esp-2020r3-win32.zip

SHA256: 81cecd5493a3fcf2118977f3fd60bd0a13a4aeac8fe6760d912f96d2c34fab66

win64

required

https://github.com/espressif/crosstool-NG/releases/download/esp-2020r3/xtensa-esp32-elf-gcc8_4_0-esp-2020r3-win64.zip

SHA256: 58419852fefb7111fdec056ac2fd7c4bd09c1f4c17610a761a97b788413527cf

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://github.com/espressif/crosstool-NG/releases/download/esp-2020r3/xtensa-esp32s2-elf-gcc8_4_0-esp-2020r3-linux-amd64.tar.gz

SHA256: 40fafa47045167feda0cd07827db5207ebfeb4a3b6b24475957a921bc92805ed

linux-armel

required

https://github.com/espressif/crosstool-NG/releases/download/esp-2020r3/xtensa-esp32s2-elf-gcc8_4_0-esp-2020r3-linux-armel.tar.gz

SHA256: 6c1efec4c7829202279388ccb388e8a17a34464bc351d677c4f04d95ea4b4ce0

linux-i686

required

https://github.com/espressif/crosstool-NG/releases/download/esp-2020r3/xtensa-esp32s2-elf-gcc8_4_0-esp-2020r3-linux-i686.tar.gz

SHA256: bd3a91166206a1a7ff7c572e15389e1938c3cdce588032a5e915be677a945638

macos

required

https://github.com/espressif/crosstool-NG/releases/download/esp-2020r3/xtensa-esp32s2-elf-gcc8_4_0-esp-2020r3-macos.tar.gz

SHA256: fe19b0c873879d8d89ec040f4db04a3ab27d769d3fd5f55fe59a28b6b111d09c

win32

required

https://github.com/espressif/crosstool-NG/releases/download/esp-2020r3/xtensa-esp32s2-elf-gcc8_4_0-esp-2020r3-win32.zip

SHA256: d078d614ae864ae4a37fcb5b83323af0a5cfdbd8243607664becdd0f977a1e33

win64

required

https://github.com/espressif/crosstool-NG/releases/download/esp-2020r3/xtensa-esp32s2-elf-gcc8_4_0-esp-2020r3-win64.zip

SHA256: 6ea78b72ec52330b69af91dbe6c77c22bdc827817f044aa30306270453032bb4

xtensa-esp32s3-elf

Toolchain for Xtensa (ESP32-S3) 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-esp32s3-elf-gcc8_4_0-esp-2020r3-linux-amd64.tar.gz

SHA256: 22bf5e63baf3f3f5103ae21bcc35d80cd888d8032095e7b9e8f9631074ac462a

linux-armel

required

https://dl.espressif.com/dl/xtensa-esp32s3-elf-gcc8_4_0-esp-2020r3-linux-armel.tar.gz

SHA256: 27f423af3cfb9d8ed7a02173ccd8dc3b0fd3b3e76a92e9ba507121e73bfa5df3

linux-i686

required

https://dl.espressif.com/dl/xtensa-esp32s3-elf-gcc8_4_0-esp-2020r3-linux-i686.tar.gz

SHA256: 479a71cfb4b0c0b36371a1aaed2e6095dfc3241937a54f60a1ba115da73ddec5

macos

required

https://dl.espressif.com/dl/xtensa-esp32s3-elf-gcc8_4_0-esp-2020r3-macos.tar.gz

SHA256: c09b8fcbb840540a3f59429b1bbfbe5abfcacccf7a8a955e4e01e3f50b53a079

win32

required

https://dl.espressif.com/dl/xtensa-esp32s3-elf-gcc8_4_0-esp-2020r3-win32.zip

SHA256: 9591fc32896b13d7fe77310afbbff197cbbc20437d316e0e2460c5c50a10d7b5

win64

required

https://dl.espressif.com/dl/xtensa-esp32s3-elf-gcc8_4_0-esp-2020r3-win64.zip

SHA256: 1caf56e9588214d8f1bc17734680ebab2906da3b5f31095e60407dad170f1221

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://dl.espressif.com/dl/toolchains/preview/riscv32-esp-elf-gcc8_4_0-crosstool-ng-1.24.0-123-g64eb9ff-linux-amd64.tar.gz

SHA256: 425454c5c4e2cde5dd2dd3a1d398befc70addf71547840fb6d0ec4b307b08894

linux-armel

required

https://dl.espressif.com/dl/toolchains/preview/riscv32-esp-elf-gcc8_4_0-crosstool-ng-1.24.0-123-g64eb9ff-linux-armel.tar.gz

SHA256: 8ae098751b5196ca8a80d832cc9930bc4d639762a6cb22be3cfe0a8d71b2f230

macos

required

https://dl.espressif.com/dl/toolchains/preview/riscv32-esp-elf-gcc8_4_0-crosstool-ng-1.24.0-123-g64eb9ff-macos.tar.gz

SHA256: 35b1aef85b7e6b4268774f627e8e835d087bcf8b9972cfb6436614aa2e40d4a9

win32

required

https://dl.espressif.com/dl/toolchains/preview/riscv32-esp-elf-gcc8_4_0-crosstool-ng-1.24.0-123-g64eb9ff-win32.zip

SHA256: 4f576b08620f57c270ac677cc94dce2767fff72d27a539e348d448f63b480d1f

win64

required

https://dl.espressif.com/dl/toolchains/preview/riscv32-esp-elf-gcc8_4_0-crosstool-ng-1.24.0-123-g64eb9ff-win64.zip

SHA256: 51e392ed88498f3fc4ad07e9ff4b5225f6533b1c363ecd7dd67c10d8d31b6b23

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 package manager. 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.16.4/cmake-3.16.4-Linux-x86_64.tar.gz

SHA256: 12a577aa04b6639766ae908f33cf70baefc11ac4499b8b1c8812d99f05fb6a02

macos

optional

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

SHA256: f60e0ef96da48725cd8da7d6abe83cd9501167aa51625c90dd4d31081a631279

win32

required

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

SHA256: f37963bcfcebdfe5864926a3623f6c21220c35790c39cd65e64bd521cbb39c55

win64

required

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

SHA256: f37963bcfcebdfe5864926a3623f6c21220c35790c39cd65e64bd521cbb39c55

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

SHA256: 77a232510625c23489d9bf1b17bdadf56e95acf8f50ef8ebff51477f23c21ef0

linux-armel

required

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

SHA256: b2cc6b7837f3cac23a752a8c43c6e0b19701ee0ec1eca4896833f0e82746062e

macos

required

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

SHA256: 97cf84dd3dfb129a7d4842599870a3b0dbb40b2713d3c5153738c44907e85d6e

win32

required

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

SHA256: b96b95607ca0c5899427f5b88cda7389da11f53ac857d3d2fe467e571af5137e

win64

required

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

SHA256: b96b95607ca0c5899427f5b88cda7389da11f53ac857d3d2fe467e571af5137e

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.

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.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

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

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.9-win64.zip

SHA256: 5816d7ec68ef3ac07b5ac9fb9837c57d2efe45b6a80a2f2bbe6b40b1c15c470e

idf-python

Embeddable Python distribution

License: PSF License

More info: tools/windows/

Platform

Required

Download

win64

optional

https://dl.espressif.com/dl/idf-python/idf-python-3.9.1-embed-win64.zip

SHA256: d5a0e625dd5b2bc6872de90292d71009c17e2396e3d1575d886a94d0dfb00c87

idf-python-wheels

Python Wheels distribution bundled for the specific version of IDF and Python

License: Open-source licenses

More info: tools/windows/

Platform

Required

Download

win64

required

https://dl.espressif.com/dl/idf-python-wheels/idf-python-wheels-idf4.3_py3.9_2021-01-07-win64.zip

SHA256: 2a33dbaa106aec9c5098b1af46f04c69923be947291c19855ff355b9707314b6

提供有关此文档的反馈