↓ Skip to main content
Developer Portal

macOS prerequisites 🍎

·2 mins·
Table of Contents
This guide outlines the preliminary steps to set up your work environment and follow the workshops.

VS Code Installation
#

This guide uses macOS Sequoia.
  • Once the file is downloaded, install VS Code
  • Press CTRL+SPACE and search for Code. Click on the VS Code icon
  • You should now see the VS Code interface

VS Code may ask whether you trust the author of the folder. This is important when using git repositories, but for now it doesn’t matter. Click “Yes.”

Installing Prerequisites
#

To install and configure the ESP-IDF toolchain, you need to have Python and git installed. In this guide, we’ll use the homebrew package manager (brew).

Installing homebrew

To install homebrew:

  • Open a terminal

  • Type:

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Python
#

The ESP-IDF toolchain uses the system version of Python. You can check the Python version by typing in the terminal:

python3 --version

If Python is not already installed, you can install it with the following command from the terminal:

brew install python3

git
#

ESP-IDF development is based on git, the version control tool used, among others, for Linux kernel development. git is the foundation upon which GitHub is built.

To install git:

  • Open a terminal

  • Install git:

    sudo brew install git

  • Verify that git was installed correctly:

    > git --version
> git version 2.43.0

Installing Additional Prerequisites
#

To use the ESP-IDF toolchain, you need to install the remaining tools.

  • Open a terminal

  • Type:

    brew install cmake ninja dfu-util

During the installation process, you may encounter some issues. Refer to the Troubleshooting section to see if your error is listed there.

Next Steps
#

Continue with the next step.

Troubleshooting
#

During the installation process, you may encounter some common errors. Below are the most frequent ones, along with their causes and solutions.

Xcode Command Line Tools Not Installed
#

Error

xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools),
missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun

Cause The Xcode command-line tools are not installed or not properly configured.

Solution

xcode-select --install

Toolchain Not Found (xtensa-esp32-elf)
#

Error

WARNING: directory for tool xtensa-esp32-elf version esp-2021r2-patch3-8.4.0 is present, but tool was not found
ERROR: tool xtensa-esp32-elf has no installed versions. Please run 'install.sh' to install it.

Cause On macOS systems with Apple Silicon architecture, some binary tools require Rosetta 2 to work.

Solution

/usr/sbin/softwareupdate --install-rosetta --agree-to-license

“Bad CPU type in executable” Error
#

Error

zsh: bad CPU type in executable: ~/.espressif/tools/xtensa-esp32-elf/esp-2021r2-patch3-8.4.0/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc

Cause The executable requires Rosetta 2 to run on macOS M1/M2/M3 systems.

Solution

/usr/sbin/softwareupdate --install-rosetta --agree-to-license

Related