ESP32 – Toolchain Installation

The last time I installed the ESP SDK for the “standard” ESP8266 modules. Now I need to install the toolchain for the new model the ESP32. This goes slightly different than the the toolchain for the ESP8266. Here I will help you setup this toolchain step by step.



Standard Setup of Toolchain for Mac OS

Install Prerequisites

Before we can install the software we need to install some software. Because I using a MacBook Pro with macOS 10.14.4 (Mojave) at this time of writing. Install pip:

sudo easy_install pip

Note: pip will be used later for installing the required Python packages.



Toolchain Setup

ESP32 toolchain for macOS is available for download from Espressif website:

Download this file, then extract it in ~/esp32 directory:

mkdir -p ~/esp32
cd ~/esp32
tar -xzf xtensa-esp32-elf-osx-1.22.0-80-g6c4433a-5.2.0.tar.gz

The toolchain will be extracted into ~/esp32/xtensa-esp32-elf/ directory.

To use it, you will need to update your PATH environment variable in ~/.profile file. To make xtensa-esp32-elf available for all terminal sessions, add the following line to your ~/.profile file:

export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH

Once you are done with setting up the toolchain then we can install ESP-IDF.



Install ESP-IDF

Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in ESP-IDF repository.

To obtain a local copy: open terminal, navigate to the directory you want to put ESP-IDF, and clone the repository using git clone command:

cd ~/esp32
git clone -b v3.2 --recursive

ESP-IDF will be downloaded into ~/esp32/esp-idf.



Setup Path to ESP-IDF

The toolchain programs access ESP-IDF using IDF_PATH environment variable. This variable should be set up on your PC, otherwise projects will not build. Setting may be done manually, each time PC is restarted. Another option is to set up it permanently by defining IDF_PATH in user profile. To do so, follow instructions

Set up IDF_PATH by adding the following line to ~/.profile file:

export IDF_PATH=~/esp/esp-idf

Log off and log in back to make this change effective.



Install the Required Python Packages

Python packages required by ESP-IDF are located in the $IDF_PATH/requirements.txt file. You can install them by running:

python -m pip install --user -r $IDF_PATH/requirements.txt


Start a Project

Now you are ready to prepare your application for ESP32. To start off quickly, we will use get-started/hello_world project from examples directory in IDF.

Copy get-started/hello_world to ~/esp directory:

cd ~/esp32
cp -r $IDF_PATH/examples/get-started/hello_world .

You can also find a range of example projects under the examples directory in ESP-IDF. These example project directories can be copied in the same way as presented above, to begin your own projects.




Being in terminal window, go to directory of hello_world application by typing cd ~/esp32/hello_world. Then start project configuration utility menuconfig:

cd ~/esp32/hello_world
make menuconfig

If previous steps have been done correctly, the following menu will be displayed:

In the menu, navigate to Serial flasher config > Default serial port to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting < Save > and then exit application by selecting < Exit >.

Here are couple of tips on navigation and use of menuconfig:

Use up & down arrow keys to navigate the menu.
Use Enter key to go into a submenu, Escape key to go out or to exit.
Type ? to see a help screen. Enter key exits the help screen.
Use Space key, or Y and N keys to enable (Yes) and disable (No) configuration items with checkboxes “[*]
Pressing ? while highlighting a configuration item displays help about that item.
Type / to search the configuration items.



Build and Flash

Now you can build and flash the application. Run:

make flash

This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your ESP32 board. That’s it you are ready to compile your code.




Easy Installation

I also made a bash Script for easy installation an a macOS. First run by opening a terminal and typing:


When the first part is installed it will reboot your Mac. Then run by opening a terminal and typing:


Now you are ready to Compile your code!


Download these scripts on my GitHub here.

Scroll to Top