Setup Toolchain for Mac OS from Scratch (Legacy GNU Make)



Since ESP-IDF V4.0, the default build system is based on CMake. This documentation is for the legacy build system based on GNU Make. Support for this build system may be removed in future major releases.


Standard process for installing the toolchain is described here. See Customized Setup of Toolchain section for some of the reasons why installing the toolchain from scratch may be necessary.

Install Prerequisites

  • install pip:

    sudo easy_install pip


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

Compile the Toolchain from Source

  • Install dependencies:

    • Install either MacPorts or homebrew package manager. MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools.

    • with MacPorts:

      sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake
    • with homebrew:

      brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake

Create a case-sensitive filesystem image:

hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"

Mount it:

hdiutil mount ~/esp/crosstool.dmg

Create a symlink to your work directory:

mkdir -p ~/esp
ln -s /Volumes/ctng ~/esp/ctng-volume

Go into the newly created directory:

cd ~/esp/ctng-volume

Download crosstool-NG and build it:

git clone
cd crosstool-NG
git checkout esp-2021r2-patch5
git submodule update --init
./bootstrap && ./configure --enable-local && make

Build the toolchain:

./ct-ng xtensa-esp32-elf
./ct-ng build
chmod -R u+w builds/xtensa-esp32-elf

Toolchain will be built in ~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf. Follow instructions for standard setup to add the toolchain to your PATH.

Next Steps

To carry on with development environment setup, proceed to section Step 2. Get ESP-IDF.