Installing ESP-IDF on WSL2

I have found WSL2 to be a wonderful addition to Windows which simplifies building projects that originated on Linux or OSX. I have now started to rely on WSL2 as the primary build system for most of my projects so it makes sense to document getting a new machine set-up for building – in this case Espressif ESP32 projects – on WSL2.

While the instructions on the Espressif website for installing the ESP-IDF development toolchain is quite well written, for me currently it fails in two important regards:

  • installing on Ubuntu 20.04 results in a problem with Python
  • if a specific version of the IDF is to be targeted then it needs to be selected before the tools are installed (or tools need to be re-installed after any change).

Hence I felt it might be helpful to document the steps which result in a successful installation on WSL2 as I use that all the time now.


The first step, if you haven’t already done so, is to install WSL2. There is a good tutorial on the Microsoft website which worked for me with no changes – although I did have to make sure that Windows 10 had fully updated – this took several repeats of going to the Updates page and requesting that Windows check for updates, install pending updates, or reboot.

Note that you need to follow all the steps, including downloading Ubuntu 20.04 from the Windows Store and installing it – then setting a username and password.


First step is to install pre-requisites:

sudo apt-get install python3 python3-pip python3-setuptoolssudo git wget flex bison gperf cmake ninja-build ccache libffi-dev libssl-dev dfu-util

Selecting the Right Python

The next step with a new Ubuntu 20.04 install is to ensure that Python 3 is the default python. Espressif’s way to do this is as follows:

update-alternatives --install /usr/bin/python python /usr/bin/python3 10

Downloading the IDF

Next step is to download the IDF

mkdir -p ~/esp
cd ~/esp
git clone --recursive

Now Select the Version of IDF

For instance to select V4.0.1 of the IDF:

cd ~/esp/esp-idf
git fetch
git checkout v4.0.1
git submodule update --init --recursive

Install the IDF Tools

The final step in the installation is to install the IDF tools:

cd ~/esp/esp-idf

Using ESP IDF to Build a Project

Assuming that you have a project cloned from GitHub or similar then you will need to change directory to the root folder of that project and then run the following:

. $HOME/esp/esp-idf/ build

The script sets the environment variables so that the IDF tools can be found.

There are many other commands that can be used and these are documented:

In some of my projects I place a shell script in the root of the project to simplify the build process. This may require editing to work with the locations of your IDF but should work in standard cases. In many cases the script needs to be made executable before use:

chmod +x ./

And also note that if you did the cloning from GitHub or editing in a Windows command prompt or VSCode local (as opposed to remote using WSL2) then the line-endings of files are most-probably going to be Windows style – CRLF and these will need changing (in VSCode this can be done by opening the file and clicking CRLF in the bottom bar of the editor window – then changing to LF and saving).