ESP-IDF v6 — Ubuntu / Linux Setup

Install ESP-IDF v6 on Ubuntu (or any Debian-based Linux) using the ESP-IDF Installation Manager (EIM). EIM handles toolchain, Python environments and all dependencies automatically.

Prerequisites

• Ubuntu 20.04 LTS, 22.04 LTS, or 24.04 LTS (64-bit)
• sudo access
• At least 5 GB of free disk space (8 GB recommended)
• A stable internet connection (~1.5 GB download)

Step 1 — Install System Dependencies

Open a terminal and run:

sudo apt update
sudo apt install -y \
  git \
  cmake \
  ninja-build \
  python3 \
  python3-pip \
  python3-venv \
  libffi-dev \
  libssl-dev \
  dfu-util \
  libusb-1.0-0

Step 2 — Add User to dialout Group

This allows your user to access serial ports without sudo:

sudo usermod -aG dialout $USER

Verify after logging back in:

groups
# Expected output includes: dialout

Step 3 — Install EIM

Option A — APT Repository (Recommended for Ubuntu/Debian)

This is the official Espressif APT repository — the cleanest method for Ubuntu:

# Add the Espressif APT repository
echo "deb [trusted=yes] https://dl.espressif.com/dl/eim/apt/ stable main" | \
  sudo tee /etc/apt/sources.list.d/espressif.list

# Update package lists
sudo apt update

# Install CLI only
sudo apt install eim-cli

# Or install GUI + CLI
sudo apt install eim

Option B — Homebrew (Alternative)

If you use Homebrew on Linux:

# Add the Espressif tap
brew tap espressif/eim

# Install CLI
brew install eim

# Or install GUI (requires a graphical environment)
brew install --cask eim-gui

Option C — Download Binary Directly

# Download latest EIM release for Linux x86_64
curl -LO https://dl.espressif.com/dl/eim/eim-linux-x86_64.tar.gz

# Extract
tar -xzf eim-linux-x86_64.tar.gz

# Move to a directory in your PATH
sudo mv eim /usr/local/bin/

Verify EIM installed correctly:

eim --version

Step 4 — Install ESP-IDF v6 Using EIM

Option A — CLI Installation (Recommended for Ubuntu)

# 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

Option B — GUI Installation

If you installed the EIM GUI version:

# Launch EIM GUI
eim

1. Click "New Installation" → "Start Installation"

2. Under Easy Installation click "Start Easy Installation"
3. EIM checks prerequisites — if all pass, click "Start Installation"
4. Wait for completion — takes 10–20 minutes depending on internet speed
5. Installation Complete page confirms success

Step 5 — Activate the ESP-IDF Environment

# Activate ESP-IDF in the current terminal session
. $HOME/.espressif/esp-idf-v6.0/export.sh

Verify:

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

Create an Alias for Convenience

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

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

Step 6 — Verify USB Device Detection

Linux generally includes drivers for CP210x and CH340 out of the box. Connect your ESP32 board via USB and verify it is detected:

ls /dev/ttyUSB* /dev/ttyACM*
# Expected: /dev/ttyUSB0 or /dev/ttyACM0

If the device is not listed, check kernel messages:

dmesg | grep -i "tty\|usb\|ch34\|cp21" | tail -20

For CH340-based boards on some systems, load the driver manually:

# Check if driver is loaded
lsmod | grep ch341

# Load manually if not loaded
sudo modprobe ch341

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/ttyUSB* /dev/ttyACM*

Flash and open the serial monitor:

# Replace /dev/ttyUSB0 with your actual port
idf.py -p /dev/ttyUSB0 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 Ubuntu environment is ready!

Troubleshooting

/dev/ttyUSB0: Permission denied

You have not logged out and back in after adding yourself to the dialout group. Log out and log back in. As a temporary workaround:

sudo chmod 666 /dev/ttyUSB0

eim: command not found

If installed via APT, make sure /usr/bin is in your PATH. If installed via binary download, make sure you moved it to /usr/local/bin/.

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

idf.py set-target fails

Run get_idf first to activate the ESP-IDF environment, then retry the command.

Python package installation errors

Make sure python3-venv is installed:

sudo apt install python3-venv

EIM download is slow

Use the Espressif China mirror:

eim install -i v6.0.1 --mirror https://dl.espressif.cn/

Build fails — cmake not found

EIM installs CMake automatically. If it is still missing:

sudo apt install cmake ninja-build

Then re-run get_idf and try building again.

Next Steps

• Your First Project →
• VS Code Integration →