ESP-IDF v6 — macOS Setup

Install ESP-IDF v6 on macOS using the ESP-IDF Installation Manager (EIM). EIM handles all dependencies automatically — no manual PATH editing or Python environment setup required.

Prerequisites

• macOS 13 Ventura or later (Intel or Apple Silicon — both supported)
• At least 5 GB of free disk space (8 GB recommended)
• A stable internet connection (~1.5 GB download)
• Xcode Command Line Tools

Step 1 — Install Xcode Command Line Tools

Open Terminal and run:

xcode-select --install

A popup appears — click Install. This provides git, make, clang and other essential build utilities required by ESP-IDF.

Verify:

xcode-select -p
# Expected: /Library/Developer/CommandLineTools

git --version
# Expected: git version 2.x.x

Step 2 — Install Homebrew

If Homebrew is not already installed:

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

For Apple Silicon Macs (M1/M2/M3/M4), Homebrew installs to /opt/homebrew/. Add it to your PATH:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Verify:

brew --version

Step 3 — Install EIM via Homebrew

The recommended method for macOS is via Homebrew — this ensures EIM stays up to date automatically.

# Add the Espressif tap
brew tap espressif/eim

# Install the GUI app (launchable from Applications)
brew install --cask eim-gui

# Or install the CLI app only (runnable from terminal)
brew install eim

Verify EIM installed correctly:

eim --version

Step 4 — Install ESP-IDF v6 Using EIM

Option A — GUI Installation (Recommended)

1. Open the EIM application from Launchpad or Applications
2. Click "New Installation" → "Start Installation"

3. Under Easy Installation, click "Start Easy Installation"

   This installs the latest stable ESP-IDF with all default settings — recommended for most users.

4. EIM checks all prerequisites automatically. If all pass, the Ready to Install page appears.

5. Click "Start Installation" and monitor progress. This takes 10–20 minutes depending on internet speed.

6. Once complete, the Installation Complete page appears.

Option B — CLI Installation

# Install latest stable ESP-IDF with default settings
eim install

# Or use the interactive wizard for custom options
eim wizard

# Install a specific version — for example v6.0.1
eim install -i v6.0.1

A successful installation ends with:

INFO - Successfully installed IDF
INFO - Now you can start using IDF tools

Step 5 — Activate the ESP-IDF Environment

After installation, activate the ESP-IDF environment in your 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 this alias to your ~/.zshrc:

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

Now type get_idf in any terminal to activate ESP-IDF instantly.

Step 6 — Install USB Drivers

CP2102 / CP2104 (Most ESP32 DevKit boards)

macOS 13 and later includes a built-in driver for CP210x chips. Connect your board and check:

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

If the device does not appear:

1. Open System Settings → Privacy & Security
2. If you see a blocked system extension message — click Allow
3. Unplug and reconnect the board

CH340 / CH341 (Common on budget boards)

Download and install the macOS driver from wch-ic.com.

After installing:

1. Restart macOS
2. Go to System Settings → Privacy & Security and allow the extension
3. Reconnect the board and verify with ls /dev/cu.*

Step 7 — Build Your First Project

# Activate environment
get_idf

# Navigate to your esp folder
mkdir -p ~/esp && cd ~/esp

# Copy the hello_world example
cp -r $IDF_PATH/examples/get-started/hello_world .
cd hello_world

# Set target chip — change to esp32s3 or esp32c3 if needed
idf.py set-target esp32

# Build
idf.py build

A successful build ends with:

Project build complete. To flash, run:
  idf.py flash

Step 8 — Flash and Monitor

Connect your board via USB and identify the port:

ls /dev/cu.*

Flash and open the monitor:

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

Expected output:

Hello world!
This is esp32 chip with 2 CPU core(s), WiFi/BT/BLE
Restarting in 10 seconds...

To exit the monitor — press Ctrl + ]

🎉 Your ESP-IDF v6.0.1 macOS environment is ready!

Apple Silicon Notes

ESP-IDF v6 has native Apple Silicon (arm64) support. EIM downloads native arm64 toolchains — no Rosetta 2 required.

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

Troubleshooting

eim: command not found after Homebrew install

Make sure Homebrew's bin directory is in your PATH:

# Apple Silicon
export PATH="/opt/homebrew/bin:$PATH"

# Intel Mac
export PATH="/usr/local/bin:$PATH"

Add this line to your ~/.zshrc to make it permanent.

idf.py not found after running export.sh

Make sure you ran the script with . (dot space) at the beginning — this sources it into the current shell:

. $HOME/.espressif/esp-idf-v6.0/export.sh

/dev/cu.usbserial-* not showing

• Use a data USB cable — not a charge-only cable
• Check System Settings → Privacy & Security for blocked extensions
• Try a different USB port
• Install the correct driver for your board's USB chip

Build fails — cmake not found

EIM should install CMake automatically. If missing:

brew install cmake ninja

Then re-run get_idf and try building again.

idf.py set-target fails

Make sure the ESP-IDF environment is activated first. Run get_idf before any idf.py commands.

Next Steps

• Your First Project →
• VS Code Integration →