Chapter 4. API Guides
Any mirror server can be used provided the URL matches the github.com download URL format: the install pro-
cess will replace https://github.com with https://${IDF_GITHUB_ASSETS} for any GitHub asset
URL that it downloads.
Note: 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.
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.
Espressif Systems 1465
Submit Document Feedback
Release v4.4