ESP-IDF Multi-Version Setup on macOS / Linux

This guide describes how to install and manage multiple versions of ESP-IDF on macOS / Linux. It shows a clean and isolated installation for version v5.2.2, along with shell aliasing to easily switch between installed versions.

📦 Installing ESP-IDF v5.2.2

Create a directory for ESP-IDF v5.2.2:

mkdir -p "$HOME/espressif/v5.2.2" && cd "$HOME/espressif/v5.2.2"

Set environment variables for this version:

export IDF_TOOLS_PATH="$HOME/espressif/v5.2.2/bin"
export IDF_PATH="$HOME/espressif/v5.2.2/esp-idf"

Clone the ESP-IDF repository:

git clone -b v5.2.2 --recursive https://github.com/espressif/esp-idf.git

Install tools:

cd "$IDF_PATH"

./install.sh

Activate the environment (for current shell session):

. ./export.sh

Alternatively (single line):

export IDF_TOOLS_PATH="$HOME/espressif/v5.2.2/bin" IDF_PATH="$HOME/espressif/v5.2.2/esp-idf" && . "$IDF_PATH/export.sh"

🧹 Persistent Alias for Easy Switching

To easily switch to v5.2.2 in the future, add the following alias to your ~/.zshrc (or ~/.bashrc if using Bash):

alias idf_set_522='export IDF_TOOLS_PATH="$HOME/espressif/v5.2.2/bin" IDF_PATH="$HOME/espressif/v5.2.2/esp-idf" && . "$IDF_PATH/export.sh"'

Then run:

source ~/.zshrc  # or ~/.bashrc

Now, run:

idf_set_522

...to activate this version in any terminal session.

➕ Installing Additional ESP-IDF Versions

To install another version, repeat the same steps with a new directory and version number. For example, to install v5.4.1:

mkdir -p "$HOME/espressif/v5.4.1" && cd "$HOME/espressif/v5.4.1"
export IDF_TOOLS_PATH="$HOME/espressif/v5.4.1/bin"
export IDF_PATH="$HOME/espressif/v5.4.1/esp-idf"
git clone -b v5.4.1 --recursive https://github.com/espressif/esp-idf.git
cd "$IDF_PATH"
./install.sh

Add another alias:

alias idf_set_541='export IDF_TOOLS_PATH="$HOME/espressif/v5.4.1/bin" IDF_PATH="$HOME/espressif/v5.4.1/esp-idf" && . "$IDF_PATH/export.sh"'

🔪 Verifying

To verify the active ESP-IDF version, run:

idf.py --version

📌 Notes

Each version of ESP-IDF should have a dedicated IDF_TOOLS_PATH to keep toolchains separate.

The aliases only affect the current terminal session.

Avoid setting export.sh in your shell profile directly to keep environments clean.