VS Code and pioarduino IDE: Programming the ESP32 (Windows, Mac OS X, Linux)

Learn how to program the ESP32 boards using VS Code (Microsoft Visual Studio Code) with the pioarduino IDE extension. The pioarduino IDE extension supports the latest Arduino core for the ESP32 (version 3). We cover how to install the software on Windows, Mac OS X or Linux Ubuntu operating systems.

Getting Started Guide VS Code and pioarduino IDE Programming the ESP32 Windows, Mac OS X Linux

The PlatformIO extension used in earlier tutorials is now deprecated. To program the ESP32 in VS Code with the latest core version, we recommend using the pioarduino extension instead.

PlatformIO IDE and pioarduino IDE Extensions

The pioarduino extension is a fork of the PlatformIO extension maintained by the community that adds support for the latest Arduino core updates for the ESP32.

In earlier tutorials, we used the PlatformIO extension. However, it doesn’t support the latest ESP32 Arduino Core (v3). To address this, the community created pioarduino, a fork that supports the newest core. We’re now using pioarduino IDE instead—if you’re familiar with PlatformIO, it works the same way.

How to Program the ESP32 with VS Code and the Latest Arduino Core (version 3)?

If you’re already familiar with programming the ESP32 with VS Code, you can read this quick answer; otherwise, follow the complete tutorial afterwards.

Quick answer:

1) Install the pioarduino IDE extension on VS Code.

2) Add the following line to the platformio.ini file:

platform = https://github.com/pioarduino/platform-espressif32/releases/download/stable/platform-espressif32.zip

This line specifies a custom version of the Espressif 32 platform, maintained by pioarduino IDE, that supports the latest ESP32 Arduino core. Unlike the default PlatformIO Espressif 32 platform (which you would normally define as platform = espressif32), this URL ensures compatibility with version 3 of the ESP32 core.

Installing VS Code

Follow the next instructions to install VS Code on your Operating System:

A) Installing VS Code on Windows (Visual Studio Code)

Go to code.visualstudio.com and download the stable build for your operating system (Windows).

Download VS Code for Windows

Click on the installation wizard to start the installation and follow all the steps to complete the installation. Accept the agreement and press the Next button.

Microsoft Visual Studio Code VS Code Installation wizard

Select the following options and click Next.

Microsoft Visual Studio Code VS Code Installation wizard step 2

Press the Install button.

Microsoft Visual Studio Code VS Code Installation wizard step 3

Finally, click Finish to finish the installation.

Microsoft Visual Studio Code VS Code Installation wizard final step

Open VS Code, and you’ll be greeted by a Welcome tab with the released notes of the newest version.

VS Code Welcome Screen

That’s it. Visual Studio Code was successfully installed.

B) Installing VS Code on Mac OS X (Visual Studio Code)

Go to code.visualstudio.com and download the stable build for your operating system (Mac OS X).

Microsoft Visual Studio Code VS Code Download Page for Mac OS X

After downloading the Visual Studio Code application file, you’ll be prompted with the following message. Press the “Open” button.

Microsoft Visual Studio Code VS Code Downloading application file for Mac OS X

Or open your Downloads folder and open Visual Studio Code.

Microsoft Visual Studio Code VS Code Downloading application file for Mac OS X

After that, you’ll be greeted by a Welcome tab with the released notes of the newest version.

Microsoft Visual Studio Code VS Code Installation wizard welcome screen on Max OS X

That’s it. Visual Studio Code was successfully installed.

C) Installing VS Code on Linux Ubuntu (Visual Studio Code)

Go to code.visualstudio.com and download the stable build for your operating system (Linux Ubuntu).

Microsoft Visual Studio Code VS Code Download Page for Linux Ubuntu

Save the installation file:

Microsoft Visual Studio Code VS Code Save installation file for Linux Ubuntu

To install it, open a Terminal window, navigate to your Downloads folder and run the following command to install VS Code.

$ cd Downloads
~/Downloads $ sudo apt install ./code_1.49.1-1600299189_amd64.deb

When the installation is finished, VS Code should be available in your applications menu.

Microsoft Visual Studio Code VS Code Open application Linux Ubuntu

Open VS Code, and you’ll be greeted by a Welcome tab with the released notes of the newest version.

Microsoft Visual Studio Code VS Code Installation wizard welcome screen on Linux Ubuntu

That’s it. Visual Studio Code was successfully installed.

Installing Python on Windows

To program the ESP32 with pioarduino, you need Python 3.5 or a later version installed on your computer. Follow the instructions according to your operating system:

A) Installing Python on Windows

Go to python.org/downloads and download Python 3.13.3 or a later version.

Download Python for Windows

Open the downloaded file to start the Python installation wizard. The following windows show up.

Important: make sure you check the option Add Python to PATH. Then, you can click on the Install Now button. You may also need to check the “Use admin privileges when installing py.exe”.

add python to path - installation

If the installation is successful, you’ll get the following message.

Python installation successful

Finally, click the Close button.

Installing Python on Mac OS X

Open a Terminal window. You can open it through Spotlight Search. To launch Spotlight, click the small magnifying glass icon in your menu bar (or press Cmd+Space).

MacOS spotlight

Then, type “terminal” and click on the Terminal icon to launch it.

Mac OS Launch terminal

To install Python, I’ll be using Homebrew.  If you don’t have the brew command available, type the next command in the Terminal window:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

Here’s how it looks on the Terminal window:

Then, run the brew command to install Python 3.13:

brew install python3

Here’s how it looks on the Terminal window:

Microsoft Visual Studio Code VS Code installing Python 3 with brew command

Now, you can proceed to this section to install the pioarduino extension.

Installing Python on Linux Ubuntu

To program the ESP32 boards with pioarduino IDE, you need Python 3.5 or a later version installed on your computer.

Open the Terminal window and check that you already have Python 3 installed. Run the following command:

python3 --version

It should return the current installed version:

python 3.13.3

If you don’t have Python installed, run the next command to install it:

sudo apt install python3

Whether you already have Python installed or not, you need to run the following command to install Python utilities.

sudo apt install python3-distutils
Installing python3-distutils Linux Ubuntu for PlatformIO IDE

Installing the pioarduino IDE Extension

At this point, we can install the pioarduino IDE extension on VS Code. Open VS Code and click on the Extensions icon or click Ctrl+Shift+X to open the Extensions tab.

Search for “pioarduino”. Select the first option and click the Install button. The installation may take some time.

Installing pioarduino extension VS Code

After that, the pioarduino icon should show up on the left sidebar as well as a Home icon that redirects you to pioarduino Home. If you’ve worked with PlatformIO before, you’ll see that pioarduino looks the same.

pioarduino extension installed

That’s it, the pioarduino IDE extension was added to VS Code.

If you don’t see the pioarduino icon and the Home icon at the bottom, you may need to restart VS Code for the changes to take effect.

Either way, we recommend restarting VS Code before proceeding.

Visual Studio Quick Interface Overview

The next image illustrates the meaning of each icon on the left and bottom sidebars and respective shortcuts:

VS Code Interface Overview
  • File explorer
  • Search across files
  • Source code management (using gist)
  • Launch and debug your code
  • Manage extensions

To see all available commands, press Ctrl+Shift+P or go to View > Command Palette. If you don’t know where a command is or its shortcut, simply search for it in the Command Palette.

pioarduino IDE Overview

For you to get an overview of how pioarduino works on VS code, we’ll show you how to create, save, and upload a “Blinking LED” sketch to your ESP32 board.

Create a New Project

In VS Code, click on the pioarduino Home icon. Click on + New Project to start a new project.

Create New Project pioarduino

Give your project a name (for example Blink_LED) and select the board you’re using. In our case, we’re using the DOIT ESP32 DEVKIT V1. The Framework should be “Arduino” to use the Arduino core.

You can choose the default location to save your project or a custom location. The default location is in this path: Documents > PlatformIO > Projects. For this test, you can use the default location. Finally, press the “Finish” button.

pioarduino project wizzard

For this example, we’ll be using the DOIT ESP32 DEVKIT board. If this is your first time using VS Code with the ESP32, VS Code will download additional data about the selected board after clicking the Finish button.

The Blink_LED project should be accessible from the Explorer tab.

Blink LED project created on pioarduino

VS Code and pioarduino have a folder structure that is different from the standard .ino project. If you click on the Explorer tab, you’ll see all the files it created under your project folder. It may seem like a lot of files to work with. But, don’t worry. Usually, you’ll just need to work with one or two of those files.

pioarduino Tasks

After creating a pioarduino project (or opening an existing project), the pioarduino commands will show up in a blue bar at the bottom.

pioarduino commands

Here’s the meaning of each icon from left to right:

  • pioarduino Home
  • Build/Compile
  • Upload
  • Clean
  • Test
  • Serial Monitor
  • New Terminal

The taskbar only shows up when you are working on a pioarduino project. If no pioarduino project is open, the blue bar doesn’t show up by default in VS Code.

If you hover your mouse over the icons, it will show what each icon does. Alternatively, you can also click on the pioarduino icon to see all the Project tasks.

pioarduino project tasks

If the tasks don’t show up on your IDE when you click the icon, you may need to click on the three-dot icon at the top and enable the Project tasks, as shown below.

pioarduino enable project tasks

platformio.ini file

The platformio.ini file is the pioarduino Configuration File for your project. It shows the platform, board, and framework for your project. You can also add other configurations like libraries to be included, upload options, changing the Serial Monitor baud rate, and other configurations.

platform.ini file pioarduino
  • platform: which corresponds to the SoC (system on a chip) used by the board. To use the latest version of the Arduino core for the ESP32, you just replace the default espressif32 with the following:
platform = https://github.com/pioarduino/platform-espressif32/releases/download/stable/platform-espressif32.zip
  • board: the development board you’re using.
  • framework: the software environment that will run the project code.

If you want to use a baud rate of 115200 in your Serial Monitor, you need to add the following line to your platformio.ini file.

monitor_speed = 115200

So, it will be like this:

[env:esp32doit-devkit-v1]
platform = https://github.com/pioarduino/platform-espressif32/releases/download/stable/platform-espressif32.zip
board = esp32doit-devkit-v1
framework = arduino
monitor_speed = 115200

After that, make sure you save the changes made to the file by pressing Ctrl+S.

In this file, you can also add libraries that you want to include in your project. pioarduino will download the libraries and all their dependencies automatically. We’ll take a look at this subject later.

src folder

The src folder is your working folder. Under the src folder, there’s a main.cpp file. That’s where you write your code. Click on that file. The structure of an Arduino program should open with the setup() and loop() functions.

pioarduino vs code src folder

In pioarduino, all your Arduino sketches should start with #include <Arduino.h>.

Uploading Code using pioarduino

In this section, you’ll learn how to upload code using pioarduino. As an example, we’re providing a code that blinks the ESP32 on-board LED every second.

Copy the following code to your main.cpp file.

/*********
  Rui Santos & Sara Santos - Random Nerd Tutorials
  Complete project details at https://RandomNerdTutorials.com/vs-code-pioarduino-ide-esp32/
*********/

#include <Arduino.h>

#define LED 2

void setup() {
  // put your setup code here, to run once:
  Serial.begin(115200);
  pinMode(LED, OUTPUT);
}

void loop() {
  // put your main code here, to run repeatedly:
  digitalWrite(LED, HIGH);
  Serial.println("LED is on");
  delay(1000);
  digitalWrite(LED, LOW);
  Serial.println("LED is off");
  delay(1000);
}

View raw code

Press Ctrl+S or go to File > Save to save the file.

Make sure you replace the platform in your platformio.ini file with the following:

platform = https://github.com/pioarduino/platform-espressif32/releases/download/stable/platform-espressif32.zip

And that you’ve set the Serial Monitor baud rate to 115200:

monitor_speed = 115200

Save the platformio.ini file.

Now, you can click the Upload icon to compile and upload the code. Alternatively, you can go to the Project Tasks menu and select Upload.

Upload code to ESP32 pioarduino VS Code

Important: make sure you close all programs that might be using the ESP serial port. This is, make sure you don’t have an Arduino IDE window open at the same time.

If the code is successfully uploaded, you should get the following message.

pioarduino upload success

After uploading the code, the ESP32 on-board LED should be blinking every second.

ESP32 onboard LED blinking

Now, click on the Serial Monitor icon, and you should see the current LED state.

pioarduino testing ESP32 Serial Monitor

Note: if you don’t see the Terminal window, go to Terminal > New Terminal.

Detect COM Port

pioarduino will automatically detect the port your board is connected to. To check the connected devices, you can go to the pioarduino Home and click the Devices icon.

VS Code - Detect devices COM port

Installing Drivers

If you don’t see your ESP’s COM port available, it means you don’t have the drivers installed. Take a closer look at the chip next to the voltage regulator on the board and check its name. The ESP32 DEVKIT V1 DOIT board uses the CP2102 chip. Alternatively, many ESP32 boards also use the CH340 drivers.

After they are installed, restart VS Code, and you should see the COM port in the Devices menu.

If you’re having trouble installing the CP210x drivers, you can check the following tutorials:

Troubleshooting

If you get the following error while uploading the code: “Failed to connect to ESP32: Timed out waiting for packet header” it usually means that your board is not in flashing mode when you’re uploading the code. 

When this happens, you need to press the ESP32 on-board BOOT button when you start seeing many dots in the debugging window.

For more information about this issue, you can follow this guide:

Changing the Serial Monitor Baud Rate – pioarduino

The default baud rate used by pioarduino is 9600. However, it is possible to set a different value. On the File Explorer, under your project folder, open the platformio.ini file and add the following line:

monitor_speed = YOUR_DESIRED_BAUD_RATE

For example:

monitor_speed = 115200

After that, save your platformio.ini file.

Installing Libraries on pioarduino

pioarduino has a powerful built-in Library Manager. It allows you to set custom dependencies per project in the platformio.ini configuration file using lib_deps. This tells PlatformIO to automatically download the library and all its dependencies when you save the configuration file or compile your project.

Follow the following procedure if you need to install libraries in pioarduino.

Click the Home icon to go to pioarduino Home. Select the Libraries icon on the left menu. Search for the library you want to install—for example, Adafruit_BME280.

pioarduino install libraries VS Code

Select the library you want to include in your project. Then, click Add to Project.

Add library to project VS Code

Select the project where you want to use the library.

Add project dependency pioarduino VS Code

This will add the library identifier using the lib_deps directive on the platformio.ini file. If you open your project’s platformio.ini file, it should look like the following image.

Library added to pioarduino VS Code platformio ini file

Alternatively, on the library window, you can select the Installation tab and scroll until you see the library’s identifier. You can choose any of those identifiers depending on the options you want to use. The library’s identifiers are highlighted in red in the following image.

BME280 Install Library Pioarduino VS Code with library identifier

Then, go to the platformio.ini file of your project and paste the library identifier into that file, like this:

lib_deps = adafruit/Adafruit BME280 Library@^2.2.4

If you need multiple libraries, you can separate their name by a comma or put them on different lines. For example:

lib_deps =
  arduino-libraries/Arduino_JSON @ 0.1.0
  adafruit/Adafruit BME280 Library @ ^2.1.0
  adafruit/Adafruit Unified Sensor @ ^1.1.4

PlatformIO has a built-in powerful Library Manager, that allows you to specify custom dependencies per project in the Project Configuration File platformio.ini using lib_deps. This will tell PlatformIO to automatically download the library and all its dependencies when you save the configuration file or when you compile your project.

Open a Project Folder

To open an existing project folder on pioarduino, open VS Code. Then, go to pioarduino Home and click Open Project. Navigate through the files and select your project folder.

pioarduino open project

pioarduino will open all the files within the project folder.

VS Code Color Themes

VS Code lets you choose between different color themes. Go to the Manage icon and select Color Theme.

VS Code Select Different Color Themes

You can then select from several different light and dark themes.

Shortcuts’ List

For a complete list of VS Code shortcuts for Windows, Mac OS X or Linux, use the following link as a reference:

Wrapping Up

In this tutorial, you learned how to program the ESP32 using VS Code with the pioarduino extension.

The pioarduino extension is a fork of the PlatformIO extension maintained by the community that adds support for the latest Arduino core updates for the ESP32. It supports the latest ESP32 Core version (v3)—while the PlatformIO extension used in previous projects and tutorials is currently deprecated.

We hope you found this guide useful.

We hope you’ve found this tutorial useful. If you like ESP32, check the following resources:



Learn how to build a home automation system and we’ll cover the following main subjects: Node-RED, Node-RED Dashboard, Raspberry Pi, ESP32, ESP8266, MQTT, and InfluxDB database DOWNLOAD »
Learn how to build a home automation system and we’ll cover the following main subjects: Node-RED, Node-RED Dashboard, Raspberry Pi, ESP32, ESP8266, MQTT, and InfluxDB database DOWNLOAD »

Recommended Resources

Build a Home Automation System from Scratch » With Raspberry Pi, ESP8266, Arduino, and Node-RED.

Home Automation using ESP8266 eBook and video course » Build IoT and home automation projects.

Arduino Step-by-Step Projects » Build 25 Arduino projects with our course, even with no prior experience!

What to Read Next…


Enjoyed this project? Stay updated by subscribing our newsletter!

19 thoughts on “VS Code and pioarduino IDE: Programming the ESP32 (Windows, Mac OS X, Linux)”

  1. Is this better than arduino IDE if so how
    Thanks
    Ps
    Arduino ide changes its format right after I think I know how to use it!

    Reply
    • This is better if you are working on more complex projects that need multiple files, library version management, etc…
      For basic and simple projects, Arduino IDE is mor practical.

      Regards,
      Sara

      Reply
  2. Erm… Sorry, you’ve lost me. You go to great lengths to explain how to install Python, then the example you provide is a C program. I got the impression this plugin (pioarduino) was about programming ESP chips with Micropython. Have I misunderstood?
    Thanks.

    Reply
    • This plugin is to program the board using C/C++, like you would do in Arduino IDE.
      But, to install the plugin, Python is required in your computer.
      Regards,
      Sara

      Reply
    • There are a lot of advantages using VSC instead of Arduino!
      – GitHub Version control
      – AI support by GitHub Copilot
      – Code completion and correction extensions like Intellisense
      – and many more

      If you have ever tried VSC combined with pioarduino you will never go back!

      Reply
    • All that just to light a led ??????????? No, thanks. With Android Kotlin is the same, project file, a lot of folders, all kind of settings, 50 lines of code, just to make the phone vibrate……..no thanks……….

      Reply
      • Hi.

        This is just the basic example to test and get started.
        The idea is to use VS Code for more complex projects, which is where it outstands Arduino IDE.

        For basic projects, Arduino IDE is preferable. But once you need to deal with multiple files, VS Code is better.

        Regards,
        Sara

        Reply
    • Hi.
      It depends on your projects.
      For complex projects with multiple files, VS Code is better. It’s also easier to manage library and platform versions.

      For simple, basic projects with just one file, Arduino IDE is easier and more practical.

      Regards,
      Sara

      Reply
  3. Beste,
    Er wordt enkel gesproken over ESP32 en niet over ESP8266.
    Hoe zit het met het programmeren ven ESP8266?
    Alvast bedankt voor uw antwoord.

    Reply
  4. Hello Sara and Rui,
    thanks for your latest guide.

    I have a few questions:
    What is actually the ‘Arduino core for the ESP32 (version 3)’ that you are referring to?
    What advantages does it give me?
    I am using ‘classic’ ESP32 Dev Boards with ESP32-D0WDQ6 (rev 1) chips on them,
    and Arduino IDE 2.3.6 with all boards and libraries updated.

    Do I have to uninstall the old, now deprecated PlatformIO prior to installing pioarduino?

    Thanks and best regards
    Kornel

    Reply
    • Hi.
      Version 3 of the core is the version you probably already have in your Arduino IDE if you have everything updated (if you go to Tools > Board > Boards Manager > ESP32 > you should have version 3 installed).

      Previously, we recommend using VS Code and PlaformIO IDE extension, but the PlaformIO extension is currently deprecated and not compatible with version 3. So, if anyone wants to use our codes in VS Code and platformIO, they may run into some issues.

      To use the latest version of the core in VS Code, you need a new pioarduino extension.

      There’s no need to install PlatformIO.

      If you’re ok with using Arduino IDE, you don’t need to worry about this.
      This tutorial is mainly addressed for those that already use VS Code.

      Regards,
      Sara

      Reply
  5. Hmmm, just tried this and now my Esp32 projects are flagging with numerous bizarre library errors, although the ESP8266 ones seem fine….Doh! After many hours of getting nowhere and crying quite a lot, I’m going for a clean reinstall….

    Reply
    • If you have previous projects created with PlaformIO, they won’t work with pioarduino.
      You need to start a new project so that all settings are set up according to pioarduino. Then, you can use the main.cpp files of your previous PlatformIO projects.

      Reply
  6. Thx so much for another great tutorial on my favorite website randomnerdtutorials.com for Arduino/ESP32 projects. May I draw your attention to one misleading typo in this tutorial:
    “This will add the library identifier using the lid_deps directive on the platformio.ini file.” It is the lib_deps directive instead.

    Reply
  7. Hello Sara and Rui,
    thanks for you very much for all yours interesting and very useful post.
    Two months ago, I switch from AEDUINO 1.8x to VS code and PlatformIO for ESP32 (DEVKIT V1 and 4).
    For me it seems to work very well
    Why to use pioarduino ?
    Can we install pioarduino in parrallel with PlatformIO ?
    Thanks.
    Best regards
    JPP

    Reply

Leave a Comment

Download Our Free eBooks and Resources

Get instant access to our FREE eBooks, Resources, and Exclusive Electronics Projects by entering your email address below.