Linux Environment Setup — VMware + Ubuntu + ESP-IDF 5.5.2

1. Overview

Compilation speed of ESP-IDF on Linux is significantly faster than on Windows (native GCC toolchain without intermediate layer overhead), and it avoids Windows path length limitations and encoding issues. Some features (such as audio codecs and AI XiaoZhi firmware) have strict ESP-IDF version requirements, and version switching is more flexible in a Linux environment.

This tutorial provides a pre-packaged Ubuntu 24.04 virtual machine image with ESP-IDF 6.0.2/5.5.5 + VSCode + all toolchains pre-installed. Import and it's ready to use.

The process has two steps:

1. Install VMware Workstation — Virtualization software

2. Import the virtual machine image — Load pre-configured Ubuntu + ESP-IDF environment

Snapshots have already been taken for the user inside the image. If you make mistakes or damage the environment, you can restore to a clean initial state with one click.

2. Official Environment Acquisition

If you are an advanced user and prefer to build your own environment instead of using a virtual machine, Espressif provides complete Linux installation documentation and toolchains:

General Steps for Official Manual Installation (for reference, not required):

​x
# 1. Install system dependencies
sudo apt-get install git wget flex bison gperf python3 python3-pip \
  python3-venv cmake ninja-build ccache libffi-dev libssl-dev \
  dfu-util libusb-1.0-0

# 2. Clone ESP-IDF
mkdir -p ~/esp && cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git
cd esp-idf && git checkout v5.5.5

# 3. Install toolchain
./install.sh esp32s3

# 4. Activate environment
. ./export.sh

Official manual installation takes approximately 1-2 hours (including toolchain download and compilation) and has high network requirements. To lower the barrier to entry, we provide pre-configured virtual machine images, skipping the tedious environment setup process, so readers can directly proceed to code learning.

3. Preparation

3.1 Hardware Requirements

3.2 Downloads Required

The VM image comes pre-installed with: Ubuntu 24.04, ESP-IDF 6.0.2/5.5.5, VSCode + ESP-IDF extension, CH340 driver, Python 3, Git. After importing, you can compile and flash directly without any additional configuration.

4. Enable CPU Virtualization

Virtual machines require CPU hardware virtualization support. Most laptops/desktops have it disabled by default and require manual enabling in BIOS.

4.1 Check Virtualization Status

Ctrl + Shift + Esc → Performance tab → Check "Virtualization" status in the bottom-right corner:

4.2 BIOS Enabling Steps

1. Restart the computer, press the BIOS hotkey on the boot logo screen (common: F2 / Del / F10 / Esc, depends on motherboard)

2. Go to Advanced or Configuration tab

3. Find one of the following options and set it to Enabled:

   Common Names in BIOS
   Intel Virtualization Technology (VT-x)
   AMD SVM Mode
   Virtualization Technology
   SVM

4. Press F10 to save and exit, computer will restart automatically

5. Install VMware Workstation

5.1 Installation Steps

1. Double-click the VMware installer (e.g., VMware-workstation-full-17.6.2-24409262.exe)

2. Click Next, read the license agreement, check I accept the terms in the license agreement

   

   

3. Choose installation path (recommended to keep default C:\Program Files (x86)\VMware\VMware Workstation\), click Next

   

4. Uncheck Check for product updates on startup and Join the VMware Customer Experience Improvement Program, click Next

   

5. Check Desktop and Start Menu shortcuts, click Next

   

6. Click Install/Upgrade, wait for installation to complete

   

7. Click License to enter a key, or choose Try for 30 days, click Finish

VMware Workstation 17 Personal is now free for individuals. You can register for a free account on the VMware website to get it.

6. Import Virtual Machine Image

6.1 Extract the Image

Extract the downloaded VM image archive (e.g., Ubuntu24.04-ESP-IDF.7z) to a disk directory with ≥ 100 GB free space.

xxxxxxxxxx
D:\Ubuntu\
├── Ubuntu24.04-ESP-IDF.vmx           ← VM configuration file (double-click to open)
├── Ubuntu24.04-ESP-IDF.vmdk          ← Virtual disk (~65 GB)
├── Ubuntu24.04-ESP-IDF-sXXXX.vmdk    ← Snapshot data
└── ...

6.2 Open the Virtual Machine

1. Open VMware Workstation, click Open a Virtual Machine

2. Navigate to the extracted directory, select Ubuntu 64-bit.vmx, click Open

3. The VM appears in the left list, named Ubuntu 64-bit

   

6.3 Adjust VM Settings (As Needed)

Click Edit virtual machine settings (or right-click → Settings), adjust based on your physical machine configuration:

Allocating too much memory and CPU may cause the host machine to lag. Recommended not to exceed 50% of the host's physical configuration.

6.4 Start the Virtual Machine

1. Click Power on this virtual machine

2. On first boot, you may be prompted "I moved the virtual machine" or "I copied it" — select I moved the virtual machine (preserves MAC address and network configuration)

3. Login password: 1

4. Wait for Ubuntu to boot (~30-60 seconds), auto-login to desktop

   

6.5 VM Environment Overview

After login, the desktop and taskbar are ready:

6.6 Snapshot Management

The VM supports snapshots, allowing you to save the current state as a restore point:

• Take Snapshot: VMware menu → VM → Snapshot → Take Snapshot, enter a name (e.g., "Initial Environment-ESP-IDF 6.0.2/5.5.2")

• Restore Snapshot: VMware menu → VM → Snapshot → Select the corresponding snapshot → Go to

It is recommended to take a snapshot immediately after completing the environment setup. If you make mistakes later or the system becomes corrupted, you can restore with one click.

7. Connect Development Board to VM

7.1 USB Passthrough

1. Connect the ESP32-S3 development board to the computer using a USB cable

2. In VMware menu: VM → Removable Devices → Find the corresponding USB device → Click Connect (disconnect from host)

3. A checkmark √ appears next to the device, indicating it has been passed through to the VM

After passthrough, the development board is only recognized by the VM, and it will temporarily disappear from the host's (Windows) Device Manager. It will automatically return to Windows after disconnecting from the VM.

7.2 Verify Serial Port

Open Terminal inside the VM (Ctrl + Alt + T), execute:

xxxxxxxxxx
ls /dev/ttyUSB*      # CH340 driver    → /dev/ttyUSB0
ls /dev/ttyACM*      # CP2102 driver   → /dev/ttyACM0

If /dev/ttyUSB0 appears, the development board has been correctly recognized by the VM.

If there is no output, check if USB passthrough was successful (VMware bottom-right USB icon status), or reconnect the USB cable.

8. Build Verification

Open the project in VSCode, or use the terminal to verify the environment:

xxxxxxxxxx
# Activate ESP-IDF environment
source ~/esp/esp-idf/export.sh

# Enter hello_world example
cd ~/esp/esp-idf/examples/get-started/hello_world

# Set target chip
idf.py set-target esp32s3

# Build
idf.py build

# Flash (/dev/ttyUSB0 replaced with actual serial port)
idf.py -p /dev/ttyUSB0 flash

# Monitor
idf.py -p /dev/ttyUSB0 monitor

Build success indicator:

xxxxxxxxxx
Project build complete.

9. FAQ

10. Appendix: Complete Official Manual Installation Guide

The VM we provide has already completed all the following steps for you. If you choose not to use a VM, below is the complete installation process recommended by Espressif.

Official Documentation Links

Version Selection Recommendations

ESP-IDF 5.x and 6.0.x have many API incompatibilities (esp_netif interface restructuring, Wi-Fi driver changes, etc.). Some open-source projects have not yet adapted to 6.0.x. ** beginners are recommended to follow the tutorial and use v6.0.2**, as the environment is most mature.