ESP-IDF Setup

This tutorial walks through installing ESP-IDF inside Visual Studio Code. By the end, you will have a working toolchain that can compile and flash firmware to the ESP32-P4.

Minimum version requirement

ESP-IDF version v5.3.1 or later is required for ESP32-P4 support. Earlier versions do not include the necessary HAL drivers or partition table definitions for this chip.

Platform prerequisites

Before installing VSCode and the ESP-IDF extension, your operating system needs certain build dependencies.

Linux (Ubuntu/Debian)

Install the required system packages:

sudo apt update
sudo apt 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

See the full list at Espressif’s Linux prerequisites.

macOS

Install Xcode command line tools and Homebrew dependencies:

xcode-select --install
brew install cmake ninja dfu-util python3

See Espressif’s macOS prerequisites for details.

Windows

Windows requires fewer manual prerequisites since the ESP-IDF installer bundles most tools. You will need:

• Git for Windows: git-scm.com
• Python 3.9+: python.org (check “Add to PATH” during install)

See Espressif’s Windows prerequisites for the full walkthrough.

Install VSCode

1. Download Visual Studio Code from code.visualstudio.com.

2. Run the installer for your platform.

3. Launch VSCode and verify it opens correctly.

Install the ESP-IDF extension

1. Open VSCode and navigate to the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X).

2. Search for “ESP-IDF” and install the extension published by Espressif Systems.

3. After installation, the ESP-IDF setup wizard should open automatically. If it does not, open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run ESP-IDF: Configure ESP-IDF Extension.

4. Select EXPRESS install mode. This is the simplest path — it downloads and configures everything for you.

5. When prompted for the ESP-IDF version, select v5.3.1 or later (v5.4.x is recommended if available).

6. Choose an installation directory. The defaults are usually fine:

   • Linux/macOS: ~/esp/esp-idf
   • Windows: C:\Espressif\frameworks\esp-idf

7. Click Install and wait for the process to complete.

Installation takes time

The EXPRESS install downloads the entire ESP-IDF framework, all toolchains (compiler, debugger, linker), and Python dependencies. On a typical broadband connection this takes 15—30 minutes. On slower connections it can take over an hour.

Do not attempt to build a project while the installation is still running. The toolchain files will be incomplete and the build will fail with confusing errors.

Network errors during install

If the installation fails with TLS/SSL errors or stalls during download:

1. Close VSCode completely.
2. Delete the partially installed directories:
   • Linux/macOS: rm -rf ~/esp/esp-idf ~/.espressif
   • Windows: Delete C:\Espressif\ and C:\Users\<you>\.espressif\
3. Ensure you have a stable network connection (wired is preferred).
4. Reopen VSCode and run the setup wizard again.

Corporate proxies and VPNs are common sources of TLS errors.

Verify the installation

1. Open the Command Palette and run ESP-IDF: Show Examples Projects.

2. Select hello_world from the get-started category.

3. Choose a directory to create the project in.

4. At the bottom status bar, click the chip target selector and choose ESP32-P4.

5. Open the integrated terminal (Ctrl+`) and run:

   idf.py --version

   You should see the ESP-IDF version (v5.3.1+).

Notes on ESP32-P4 clock speed

The ESP32-P4 features a dual-core RISC-V processor. The current ESP-IDF SDK configures the CPU clock at 360 MHz by default. While the silicon supports 400 MHz, full SDK support for that clock rate is not yet available. For most workloads the difference is negligible, and 360 MHz provides stable operation across all supported peripherals.

What to do next

Your toolchain is ready. Proceed to First Flash to connect the board and upload your first program.