ESP-IDF on WSL2 – Build, Flash and Monitor

After I published a post about idfx (tool for flashing ESP-IDF applications on WSL2) I have decided to describe in this post a complete process about how to install ESP-IDF on WSL2 and how to use idfx.

This post is written form of my youtube video about the same topic. I have decided to wrote this post along with the video because it will be much easier for you to just copy and paste commands inside of your WSL2.

Just like idfx, this process of installation ESP-IDF on WSL2 is tested under Ubuntu 20.04 LTS and Debian distributions, and as a prerequisite for using idfxPython needs to be installed on the Windows.

After this short intro, you can open WSL2 and start to execute next commands.

ESP-IDF installation

  • Update linux
sudo apt update && sudo apt upgrade -y
  • Install tools required for esp-idf
sudo apt install -y git wget curl flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0
  • Make python3 as default python
sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 1
  • Make pip3 as default pip
sudo update-alternatives --install /usr/bin/pip pip /usr/bin/pip3 1
  • Make esp directory and go inside
cd ~ && mkdir esp && cd esp
  • Clone esp-idf repository (this will take a while…)
git clone --recursive
  • Modify esp-idf installation script to work with WSL
cd esp-idf && ! grep -q "dirname --"; [ $? -eq 0 ] && sed -i 's/dirname/dirname --/g'
  • Run esp-idf installation script
. ./ || true
  • Add esp-idf export script to the user profile script in order to make isp-idf tools visible on the PATH for every session
echo -e '\n\n. $HOME/esp/esp-idf/ > /dev/null 2>&1 || true' >> ~/.profile
  • Install idfx
curl --create-dirs -L -o $HOME/bin/idfx && chmod u+x $HOME/bin/idfx
  • Source profile script to add all necessary tools to the PATH
. ~/.profile || true

Create (a copy of hello_world) project

  • Make a copy of hello_world example project in home directory
cd ~ && cp -r $IDF_PATH/examples/get-started/hello_world .

Build, flash and monitor

  • Go inside of project
cd hello_world
  • Set target to ESP32 (or other ESP chip) set-target esp32
  • Configure menuconfig
  • Now we can build, flash and monitor our application with a single command:
idfx all COM2

Where in previous command COM2 is the COM port of my ESP32. Open Device Manager on Windows to find COM port of your ESP.

(To exit from monitor press CTRL+] or CTRL+T,X)

That’s it.
Happy coding and flashing! zap

9 thoughts on “ESP-IDF on WSL2 – Build, Flash and Monitor

  1. This is awesome thanks! I was curious what does the step for modifying the install script for wsl actually do?

    1. Hi Zach. That step actually just add two dashes into script to make that script possible to run under the WSL. Thanks for the comment and sorry for the late reply.

  2. Thank you for posting this! I am really new to this so this could be some issue on my part but when I try the install idfx step I get this error “/home/adrobot1314/.local/bin/idfx: No such file or directory”. Would you happen to know how to fix it? I also tried this on a different computer and ran into the same error.

    1. Hi Ariana, can you check if directory /home/adrobot1314/.local/bin even exists? If not, please try to create it manually and add it to the PATH before performing idfx install step.

      I guess you have installed Ubuntu 22.04. Just checked and saw that directory $HOME/.local/bin does not comes pre-created with Ubuntu 22.04 (while in Ubuntu 20.04 it does). However, I have modified idfx installation command in this post so you can execute it again and everything should be ok now.

      1. Hi Alija, thank you so much for looking into it and uploading a solution. I greatly appreciate it.

  3. Hi, thanks for the guide! I tried it today (2023 march 8), but end up with
    “No module named esp_idf_monitor” after the flashing is completed.

    esp_idf_monitor github repo does not seem to have any installations instructions either so I am kind of stuck due to my little knowledge of these tools and how they interact, so I would be greatful for any hints.

    Btw, “. ~/.profile || true” step, was it supposed to quit the terminal window?

Leave a Reply

Your email address will not be published. Required fields are marked *