PlatformIO ESP32 Setup: Install in VSCode, Build & Upload

PlatformIO is a build system and IDE extension for embedded projects, and it runs inside Visual Studio Code. Instead of Arduino IDE's single sketch window, you get a real editor, per-project configuration, and a command line underneath it - useful once a project grows past one file, or once you want the same project buildable by hand or in CI. This guide covers installing PlatformIO in VSCode, creating an ESP32 project, understanding platformio.ini, and building and uploading a first program, both from the toolbar and from the CLI.

Why PlatformIO (and why not)

PlatformIO is not a strict upgrade over Arduino IDE - it trades away some of Arduino IDE's simplicity for structure that pays off on bigger projects. Worth knowing before you install it:

If you are making your first blink sketch, Arduino IDE is the faster path. If you already know you want VSCode, or you are about to start a project with more than one source file, PlatformIO is worth the setup.

1Install VSCode and the PlatformIO IDE extension

1. Download and install Visual Studio Code for your OS, if you do not already have it.
2. Open VSCode and go to the Extensions view (the square-icon tab in the left sidebar, or Cmd/Ctrl+Shift+X).
3. Search for platformio ide and install the official PlatformIO IDE extension.
4. Wait for the install to finish - PlatformIO's own Core tooling installs in the background the first time, which takes a few minutes.

Per the official PlatformIO VSCode docs: install VSCode, open its Extensions view, search for the official platformio ide extension, and install it - PlatformIO Home then opens automatically, with a button in the toolbar to reopen it any time.

2Create a new ESP32 project

Open PIO Home (the house icon in the PlatformIO sidebar, or the toolbar's Home button), click New Project, and fill in the wizard:

1. Name: anything - for example esp32-blink.
2. Board: search for your board. Most classic 30-pin ESP32 devkits match Espressif ESP32 Dev Module; C3 and S3 boards have their own entries. Not sure which one is yours? Find your board among 270+ pages →
3. Framework: Arduino - it gives you the same digitalWrite/Serial API as Arduino IDE, just built by PlatformIO instead.
4. Click Finish and wait - PlatformIO creates the project folder and downloads the platform packages for that board.

A new PlatformIO project has a fixed layout:

esp32-blink/
  platformio.ini   # project configuration - board, framework, settings
  src/
    main.cpp       # your program (setup()/loop(), same as a .ino)
  include/         # project-specific headers
  lib/             # project-specific libraries
  .pio/            # build output - generated, do not edit or commit

3Understand platformio.ini

Every PlatformIO project is defined by one file, platformio.ini, sitting at the project root. This is the version verified for this guide - one environment, targeting a classic ESP32 devkit with the Arduino framework:

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200

• [env:esp32dev] - an environment name. A project can define several (different boards, different build flags) and build them independently.
• platform = espressif32 - the Espressif 32 platform package: the toolchain, upload tool, and board definitions for every ESP32 variant.
• board = esp32dev - which of that platform's board definitions to build for. This is the "Espressif ESP32 Dev Module" entry from the New Project wizard; other boards use their own board ID (their page in the boards database lists it where relevant).
• framework = arduino - build against the Arduino core's APIs. PlatformIO also supports espidf and mixed arduino, espidf setups, but that is a separate guide - see ESP-IDF in VSCode.
• monitor_speed = 115200 - the baud rate pio device monitor uses. It should match the Serial.begin() call in your code.

4Build, upload, and monitor

This blink sketch is the one verified for this guide - GPIO2 is the built-in LED on most classic ESP32 devkits. If your board uses a different pin, its board page has the right number.

#include <Arduino.h>

const int ledPin = 2;  // built-in LED on most classic ESP32 devkits

void setup() {
  pinMode(ledPin, OUTPUT);
  Serial.begin(115200);
}

void loop() {
  digitalWrite(ledPin, HIGH);
  Serial.println("LED on");
  delay(1000);
  digitalWrite(ledPin, LOW);
  Serial.println("LED off");
  delay(1000);
}

PlatformIO's bottom toolbar in VSCode has one button per action: a checkmark to build, a right-arrow to upload, and a plug icon to open the serial monitor.

1. Build: click the checkmark and wait for "SUCCESS".
2. Upload: plug in your board over a USB data cable, then click the arrow and wait for "SUCCESS". This step needs a connected board - the checkmark alone (build) does not.
3. Monitor: click the plug icon to open the serial terminal and watch the LED on/off lines print.

The same three actions are plain CLI commands, and they are what the toolbar buttons run underneath. Useful in a terminal, a script, or when the buttons are not visible for some reason:

pio run

pio run -t upload

pio device monitor

The build shown in platformio.ini and src/main.cpp above was verified with pio run (compile only, no board attached): PlatformIO Core 6.1.18, Espressif 32 platform 7.1.0, SUCCESS in a few seconds, using about 7% RAM and 21% flash on a classic ESP32. Uploading and monitoring need an actual board plugged in over USB - not something this compile-only check exercises.

Where to next