· Esp32  · 6 min read

Setup ESP32 development environment on MacOS (ESP-IDF)

Setting up a robust development environment is the first step to unlocking the full potential of the ESP32 microcontroller. In this blog post, we provide a clear, step-by-step guide to configuring the ESP-IDF framework for ESP32 development on macOS. From installing the necessary tools and dependencies to setting up the ESP-IDF environment and verifying your setup, this tutorial ensures a smooth start for your ESP32 projects. Whether you’re new to embedded systems or an experienced developer, this guide will help you establish a reliable ESP32 development workflow on macOS.

Introduction

This document walks through the steps to setup a development environment for ESP32 on MacOS. The steps follow closely the official ESP32 documentation with some clarifications in each steps.

Install prerequisites

  • Install homebrew: Open a terminal and paste this line and hit Enter

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

Homebrew is a package management for Mac and Linux which can help you install various software packages. You use Homebrew to install cmake, ninja, dfu-util, ccache packages which ESP-IDF relies on. When installing homebrew, it will check if XCode Command Line Tools have been installed on your system. If not, it will download XCode Command Line Tools. The process might take a while and you might want to grab a cup of coffee.

  • After homebrew has successfully installed, you install cmake, ninja, dfu-util, ccache with homebrew

    brew install cmake ninja dfu-util ccache

  • Make sure python3 is installed on your system by running

    python3 —version

New versions of MacOS such as Big Sur or Monterey come with python3 preinstalled in the system. For previous versions of MacOS, you might need to install manually.

Download ESP-IDF from Github

First, create a directory to store ESP-IDF. We will create a new directory in the home folder by using mkdir command

mkdir ~/esp
cd ~/esp

To download ESP-IDF from Github, open a Terminal and type in

git clone -b v4.3.2 --recursive https://github.com/espressif/esp-idf.git

It takes a while to download esp-idf repository.

Setup ESP-IDF tools

After downloading ESP-IDF repository from Github, you need to run a script install.sh inside the folder esp_idf. The scripts will install a number of tools that are necessary such as compiler, debugger, python packages for creating a virtual terminal environment, etc.

First, go to the clone esp_idf folder

cd ~/esp/esp_idf

Then run the install.sh script and pass in esp32 as argument. This will install tools for working with ESP32 in the default folder ~/.espressif

./install.sh esp32

By looking at the output on the terminal, we can see that the script install a couple of esp32 tools, for example

Installing tools: xtensa-esp32-elf, esp32ulp-elf, openocd-esp32

The script also install python environment and packages

Installing Python environment and packages
Creating a new Python environment in /Users/epro/.espressif/python_env/idf4.3_py3.8_env
Installing virtualenv

And the last message printed on the terminal is

All done! You can now run:

  . ./export.sh

This message reminds you the final step which is setup environment variables, because the installed tools have not been added to PATH yet. The script export.sh does that.

We will create an alias for running export.sh from terminal. For newer MacOS, the default shell is zsh. Therefore, we need to add a line in ~/.zprofile. If you are using VSCode and have added code in the PATH, you can type

code ~/.zprofile

Then paste this line to that file and save it.

alias get_idf='. $HOME/esp/esp-idf/export.sh'

Then run this command to reload

source ~/.zprofile

Now if you run get_idf from Terminal, you will see output like this

Setting IDF_PATH to '/Users/epro/esp/esp-idf'
Detecting the Python interpreter
Checking "python" ...
Checking "python3" ...
Python 3.8.9
"python3" has been detected
Adding ESP-IDF tools to PATH...

Whenever you want to run esp32 commands, for example idf.py build, remember to run get_idf first to activate virtual environment. If you don’t, you will get error such as command not found: idf.py.

Test the setup

Now all the necessary tools have been downloaded and configured, it’s time to test the setup. We will use an existing sample project blinky in esp_idf and make sure that we can configure, compile, and flash the firmware onto a target ESP32 chip. To continue with this step, you will need an ESP32 development board. Here, we will use ESP-WROVER-KIT, however, any ESP32 development board is fine.

Connect hardware and determine serial port

First, make sure the following jumpers are set to correct position on the ESP-WROVER-KIT board:

  • Select USB as power source (USB_5V) in Jumper JP7
  • Enable UART communication using jumper JP2 (connect RXD and TXD0, TXD and RXD0). These jumpers connect the UART interface of ESP32 with the channel B of serial chip FT2232HL. This is necessary to upload code to ESP32.

Then connect your ESP-WROVER-KIT to Mac, make sure the power switch is turned to ON position. Open a terminal and type

ls /dev/tty*

You will see that the terminal display two channels of FT2232HL chip that presents on the board, for example

/dev/tty.usbserial-FD3400    (Channel A)
/dev/tty.usbserial-FD3401   (Channel B)

Note the channel B port as we will need to use it in the next step when flashing program to ESP32.

Create a new project from sample projects

Now go to ~/esp/esp_idf/examples/get-started/ folder and create a duplicate of blinky project and name it blink_copy. Then move it to ~/esp Then open a terminal and go to blinky_copy folder.

cd ~/esp/esp-idf/examples/get-started/blink_copy

Next, configure the target for the project by running

get_idf
idf.py set-target esp32

Remember that we need to run get_idf once to set environment variables for esp_idf as described in previous steps.

Modify project configuration

To modify project configuration, we run

idf.py menuconfig

In this example, we want to modify the pin that toggle the Blue LED on the ESP-WROVER-KIT board which is GPIO4. Select Example Configuration ---> in the Menu and set 4 for the option Blink GPIO number. Then press S to Save the configuration and ESC to exit menu config.

Build project

To build the project, run

idf.py build

This command will start the build process and generate binary image for uploading to the ESP32.

Flashing the firmware

To flash the firmware to ESP32, you use this command

idf.py -p /dev/tty.usbserial-FD3401 flash

Note that we specify the port /dev/tty.usbserial-FD3401 as the argument for -p option. If everything is running correctly, you will see the Blue LED flash on and off every second.

Monitor

To see log messages that are flushed through serial port, you use monitor utility. Run

idf.py -p /dev/tty.usbserial-FD3401 monitor

You should see log messages printed on terminal, like so

I (307) cpu_start: Starting scheduler on PRO CPU.
I (0) cpu_start: Starting scheduler on APP CPU.
I (318) gpio: GPIO[4]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
Turning off the LED
Turning on the LED
Turning off the LED
Turning on the LED
Turning off the LED
Turning on the LED
Turning off the LED

This is useful when you are developing applications and want to know where is the current progress of the code execution. To exit the monitor, press Ctrl + ].

Conclusion

Phew! That was quite a bit of setting up. If you have followed along, congratulation on completing the first step to ESP32 development with ESP-IDF. This first step is essential to continue with learning to program ESP32.

    Related articles

    View All Articles »

    Why OTA for ESP32 Is Still Too Hard — and What I'm Building to Fix It

    Over-the-air (OTA) firmware updates are critical for modern embedded devices, but implementing a secure, automated OTA system on the ESP32 is still more complex than it should be. In this post, I break down the current state of OTA for ESP32, common pain points with existing solutions, and why I’m building an open-source, developer-friendly OTA update system with CI/CD support, firmware signing, and a lightweight OTA agent.

    Task Synchronization with FreeRTOS Event Groups on ESP32 (ESP-WROVER-KIT Example)

    FreeRTOS event groups provide an efficient way to synchronize tasks based on multiple conditions using binary flags. In this post, we explore how to use event groups on the ESP-WROVER-KIT with ESP-IDF. Through a practical example involving sensor and network initialization, we demonstrate how event bits can signal system readiness to a processing task. This approach enables clean, scalable task coordination in real-time embedded applications using the ESP32.

    Using FreeRTOS Mutex with ESP-WROVER-KIT for Resource Protection

    FreeRTOS mutexes are essential for managing shared resources in embedded systems, ensuring that only one task accesses a resource at a time. In this post, we explore how mutexes work in FreeRTOS and demonstrate their use on the ESP-WROVER-KIT by protecting UART output shared between two tasks. This practical example shows how to prevent race conditions and output conflicts, while highlighting the importance of mutual exclusion in real-time applications on the ESP32 platform.