ESP-IDF v6 — Ubuntu / Linux Setup

Install ESP-IDF v6 on Ubuntu (or any Debian-based Linux) using EIM. This guide covers everything from system dependencies to flashing your first ESP32 project.

Prerequisites

• Ubuntu 22.04 LTS or 24.04 LTS (64-bit)
• sudo access
• At least 4 GB of free disk space
• Stable internet connection

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: ... dialout ...

Step 3 — Install EIM

Option A: Download the EIM binary (Recommended)

# Download the latest EIM release for Linux
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 --version

Option B: Using snap (Ubuntu 22.04+)

sudo snap install eim

Step 4 — Install ESP-IDF v6 via EIM

CLI Installation (Recommended for Ubuntu)

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

# For ESP32-S3
eim install --version v6.0 --target esp32s3

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

# Install for multiple targets at once
eim install --version v6.0 --target esp32,esp32s3,esp32c6

EIM will download the framework, toolchain, and all required Python packages into ~/.espressif/.

GUI Installation (optional)

If EIM has a GUI available on your system, launch it with:

eim &

Follow the same wizard steps as the Windows GUI guide.

Step 5 — Activate the ESP-IDF Environment

# Source the environment activation script
. $HOME/.espressif/esp-idf-v6.0/export.sh

Verify:

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

Make Activation Automatic

Add the export line to your ~/.bashrc (or ~/.zshrc if using Zsh):

echo '. $HOME/.espressif/esp-idf-v6.0/export.sh' >> ~/.bashrc
source ~/.bashrc

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

Step 6 — Install USB Drivers (Usually Pre-installed)

Linux generally includes drivers for CP210x and CH340 out of the box. Verify your board is detected:

# Connect your ESP32 board via USB, then:
ls /dev/ttyUSB* /dev/ttyACM*

Expected output: /dev/ttyUSB0 or /dev/ttyACM0

If the device is not listed:

# Check kernel messages for USB device
dmesg | grep -i "tty\|usb\|ch34\|cp21" | tail -20

For CH340-based boards on some systems:

# Check if driver is loaded
lsmod | grep ch341

# Load manually if not loaded
sudo modprobe ch341

Step 7 — Build and Flash the Hello World Project

# Activate ESP-IDF
. $HOME/.espressif/esp-idf-v6.0/export.sh

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

# Set your chip target
idf.py set-target esp32

# Build
idf.py build

Flash and monitor (replace /dev/ttyUSB0 with your actual port):

idf.py -p /dev/ttyUSB0 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 Ubuntu environment is ready!

Troubleshooting

/dev/ttyUSB0: Permission denied

You haven't logged out and back in after adding yourself to the dialout group. Do that, or temporarily use:

sudo chmod 666 /dev/ttyUSB0

EIM download fails or is slow

Set an alternative mirror in EIM:

eim install --version v6.0 --target esp32 --mirror https://dl.espressif.cn/

Python package installation errors

Make sure you have python3-venv installed, as EIM creates a virtual environment:

sudo apt install python3-venv

Next Steps

• Your First Project →
• VS Code Integration →