ESP-IDF On VSCode On Macintosh (ESP32)

I am looking at the ESP32, as well as the Microchip version(s) of processors.

I have switched to using only VSCode for my IDE, and was applauding the fact that both Microchip and the ESP32 folks now support using VSCode on all platforms (Windows, Linux, Macintosh).

Unfortunately, the ESP-IDF documentation is a bit scatter-brained for me. That is saying something, because I am very scatter-brained. It took about two days to resolve all of the issues for me and that is a long time in my world. I will walk you through the solutions I was able to uncover for the Macintosh only. Some may apply to windows or linux, but no guarantees.

First, it works better on Ubuntu. It may work well on Windows, but WinOS is not my daily spyware environment.

So, here are the steps for installing on Macintosh, simplified. I am using OSX 15, Sequoia.

Install Steps

1. Go to https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/. It is worth a read, but your eyes will cross.
2. Install brew (https://brew.sh/)
3. Use brew to install the following: “brew install libgcrypt glib pixman sdl2 libslirp dfu-util cmake python”
4. Install Python 3.14 (as of August 2026). Goto https://www.python.org/. Download the OSX installer and install. (Yes, even though brew installed it. OSX official python is found before brew’s python in most cases, messes up the ESP-IDF environment.)
5. Install eim: “brew install –cask eim-gui” (You can also download it from espressif)
6. If not installed, install VSCode, or VSCodium. (VSCodium is the open source version that does not monitor your work)
7. In VSCode/VSCodium go to the Extensions and install ESP-IDF.
8. Open a terminal and type: “eim,” or start the installation manager from within VSCode/VSCodium.
9. Click On “Custom Installation” button (If you can’t get GUI to properly show, type “eim wizard” at the command line and follow the prompts.)
10. If it does not allow you to continue, go back and fix the requirements. (Mine was Python for a very long time)
11. Select the esp32 version you are working with (or choose the All selection). Mine was a plain esp32. The best one to get today for starting out is the ESP32-S3. If you have to go back, click on the balloon on the left hand side to go back to that page
12. I chose v6.1, as that was the latest stable release.
13. Accept the download mirror defaults
14. On the Select ESP-IDF Features screen, click on the “ci” box and the “ide” box. This supposedly selects the items you need to run with VSCode/VSCodium. You will see check boxes selected if done properly. The “easy” install did not appear to work for me.
15. I left the tools to default, as brew installs cmake. qemu should provide you a virtual machine test environment, but I did not investigate that.
16. Make note of the directory that the ESP32 development files are installed into. In my case it was “/Users/username/.espressif” That will be important.
17. Once eim finishes, click on “Home,” in the EIM. Also quit VSCode/VSCodium. This is important, because the ESP-IDF needs certain environment variables set, or it fails.
18. At this point, you have two options.
19. First option: In the EIM install manager, you can click on “Manage Installations” and click on the red “Open IDF Terminal” button at the bottom of the V6.1 rectangle. That will open a terminal window. In that window you can execute: “open /Applications/Visual\ Studio\ Code.app” That will start VSCode with all the environment variables necessary.
20. Second option: Open a terminal window and enter: “source ~/.espressif/tools/activate_idf_v6.1.sh”
21. You should get a long list of work done, then: “You are now using IDF version 6.1.0” (or whatever version you chose)
22. Open VSCode/VSCodium from this terminal window: “open /Applications/Visual\ Studio\ Code.app”
23. If the extension asks, “Activate Anyway” This allows you to go through the next few steps.
24. Use CMD-SHIFT-P and type “ESP-IDF: Select Current ESP-IDF Version
25. Select the version you just installed and press enter.
26. You will get “ESP-IDF has been Configured” If you don’t go back through the steps. I may have skipped something, or you might have.
27. Open a terminal and enter “ls /dev/tty.*”
28. Plug in the ESP32. Its power light should light.
29. Type “ls /dev/tty.*” in the terminal again. Compare the two lists to determine the serial port(s) just created for the ESP32 board.
30. You can create a new project if you wish. If so, use “blink.”
31. If you see an “ESP-IDF Basic Usage Guide” on your welcome screen in VSCode/VSCodium, you can click on it and walk through. You may have to select a framework if you have no folder open. I found it easier to copy from the examples (/Users/username/.espressif/v6.1/esp-idf/examples) into a folder you wish to save your esp32 projects into (i.e. ~/esp32_projects). Open that folder when starting VSCode to let everything stabilize before doing other work.
32. In the “New Project” screen, select your project directory. My ESP32 kit was a V1, so I chose esp32 as the ESP-IDF target
33. Click on the ESP-IDF board and choose the closest one to what you have
34. On the “Choose serial port” drop down, choose the serial port for your board.
35. If there are two new ones listed, and you are not sure which one, use screen. for example: “screen /dev/tty.SLAB_USBtoUART 115200”
36. If that command works and does not say “could not find pty” then that is the serial port to use. You may get nonsense printed on the screen, ignore for now.
37. To exit screen press ctl-a, ctl-\ and press enter. (You may have to type “reset” and press enter in the terminal to fix linefeeds and such after running screen)
38. The component directory needs to be entered if you are using components. In my machine it was /Users/username/.espressif/v6.1/esp-idf/components
39. click create project. Give it several minutes. You might think it is broken, but usually not. If it does break, simply copy from the examples folder the “blink” folder for your first test project to open.
40. Once a new project is created, a new VSCode/VSCodium window is opened. Go back through the Select Current ESP-IDF version steps, and allow the extension to create various files, etc. for your project.
41. Once you have “ESP-IDF has been configured” you are mostly there.
42. The bottom bar has all of the text based buttons for compiling and testing your system.
43. On the left hand side, the sdkconfig files contain various selections for the build. My devkitV1 has a blue LED on GPIO pin 2 based on the schematic. Open file “sdkconfig”, locate CONFIG_BLINK_GPIO=5 (or whatever number) and change it to the pin used on your board. (My =5 was changed to =2) Save and close.
44. Click on the Wrench. That should build. (Or use Cmd-P, “ESP-IDF: Build your project”
45. Once it is finished building and gives you a memory map, click on the lightning button.
46. Choose UART as the programming type.
47. Once it says “Flash Done” your LED should be blinking.
48. Click on the “monitor terminal” icon next to the lightning bolt to monitor the output of the serial port. It will say the LED is ON and LED is OFF
49. To exit the monitor, type clt-]
50. You can also use “screen” as indicated above to see the serial port output.

The ESP-32 DevKitV1 does not allow you to debug unless you buy an external board. You can get this from Amazon, and ESP-PROG or ESP-PROG2.

Later, you may be able to re-launch VSCode/VSCodium and have everything magically work, if you have it set to re-open folders at start. I was unable to do this the first few times, but after I rebooted my macintosh it reopened the project folder and magically worked without other issues. This was after a notification that the extension was magically updated to version 2.2.

Fini

ESP-IDF is powerful, annoying, and useful. Once I get the proper version of ESP32-S3 board and make debugging work, I will log my results.

Enjoy!