ESP-IDF v6 — macOS Setup

Install ESP-IDF v6 on macOS using Homebrew and EIM. This is the cleanest and most maintainable approach on macOS — no manual PATH editing required.

Prerequisites

• macOS 13 Ventura or later (Intel or Apple Silicon — both supported)
• Xcode Command Line Tools
• Homebrew
• At least 4 GB of free disk space

Step 1 — Install Xcode Command Line Tools

If you haven't already, install the Xcode Command Line Tools:

xcode-select --install

A popup will appear — click Install. This provides git, make, clang, and other essential build utilities.

Verify:

xcode-select -p
# Expected: /Library/Developer/CommandLineTools
git --version
# Expected: git version 2.x.x

Step 2 — Install Homebrew

If Homebrew is not installed:

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

For Apple Silicon Macs, Homebrew installs to /opt/homebrew/. Make sure it's in your PATH:

# For Apple Silicon (M1/M2/M3/M4)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# Verify
brew --version

Step 3 — Install EIM via Homebrew

# Add the Espressif tap
brew tap espressif/tap

# Install EIM
brew install eim

# Verify
eim --version

Step 4 — Install ESP-IDF v6

CLI Installation

# Install ESP-IDF v6.0 for ESP32
eim install --version v6.0 --target esp32

# For ESP32-S3 (used in Analog Data Edge AI boards)
eim install --version v6.0 --target esp32s3

# For ESP32-C6
eim install --version v6.0 --target esp32c6

EIM installs everything into ~/.espressif/ including the Xtensa/RISC-V toolchains and Python virtual environments.

GUI Installation (Optional)

# Open the EIM GUI
eim --gui

Follow the wizard: select version → select target → install.

Step 5 — Activate the ESP-IDF Environment

# Source the export script to activate ESP-IDF in current terminal
. $HOME/.espressif/esp-idf-v6.0/export.sh

Verify:

idf.py --version
# Expected: ESP-IDF v6.0.x

Create an Alias for Convenience

Add an alias to your ~/.zshrc (macOS default since Catalina):

echo "alias get_idf='. \$HOME/.espressif/esp-idf-v6.0/export.sh'" >> ~/.zshrc
source ~/.zshrc

Now you can simply type get_idf in any terminal to activate your ESP-IDF environment.

Step 6 — Install CP210x Driver (ESP32 DevKit boards)

Most ESP32 DevKit boards use the CP2102 USB chip. macOS 13+ includes a driver for this, but you may need to explicitly allow it in Security settings.

1. Connect your ESP32 board via USB
2. Open System Settings → Privacy & Security
3. If you see a message about a blocked system extension, click Allow
4. Reconnect the board

Verify the device is detected:

ls /dev/cu.*
# Expected: /dev/cu.usbserial-0001 or /dev/cu.SLAB_USBtoUART

Step 7 — Build and Flash the Hello World Project

# Activate environment
get_idf

# Create hello world project
idf.py create-project-from-example "esp_system:hello_world"
cd hello_world

# Set chip target (change if using ESP32-S3 or C6)
idf.py set-target esp32

# Build
idf.py build

Flash and monitor:

# Replace with your actual port
idf.py -p /dev/cu.usbserial-0001 flash monitor

Exit the monitor with Ctrl + ].

Expected output:

Hello world!
This is esp32 chip with 2 CPU core(s), WiFi/BT/BLE, silicon revision v3.1, 4MB external flash
Restarting in 10 seconds...

🎉 Your ESP-IDF v6 macOS environment is ready!

Apple Silicon Notes

ESP-IDF v6 has native Apple Silicon (arm64) support. The toolchains downloaded by EIM are native binaries — no Rosetta 2 required.

If you have an older ESP-IDF installation that required Rosetta, reinstall via EIM to get the native arm64 toolchain for significantly faster build times.

Troubleshooting

eim: command not found after Homebrew install

Make sure Homebrew's bin directory is in your PATH. For Apple Silicon:

export PATH="/opt/homebrew/bin:$PATH"

For Intel Mac:

export PATH="/usr/local/bin:$PATH"

/dev/cu.usbserial-* not showing up

• Try a different USB cable (use a data cable, not a charge-only cable)
• Check System Settings → Privacy & Security for blocked extensions
• Try a different USB port or hub

Build fails with "command not found: cmake"

EIM should install cmake. If not:

brew install cmake ninja

Next Steps

• Your First Project →
• VS Code Integration →