Build Configurations

New in version 3.6.1.

There are 2 types of build configurations in PlatformIO:

Release:Default configuration. The release configuration of your firmware/program does not contain symbolic debug information and is fully optimized.
Debug:The debug configuration of your firmware/program is compiled with full symbolic debug information and no optimization. Optimization complicates debugging, because the relationship between source code and generated instructions is more complex.

As we mentioned before, PlatformIO builds project in Release configuration by default. You can build project in Debug configuration using one of these options:

PIO Unified Debugger automatically switches to “Debug” configuration when you do project debugging from PlatformIO IDE or use platformio debug command.


If you use the same build environment for “Release” and for PIO Unified Debugger, PlatformIO will rebuild your project each time when you switch between build configurations. To avoid this issue, please declare 2 separate project build environments in “platformio.ini” (Project Configuration File) as described below in example.

Otherwise, please add targets = debug to your build environment and PlatformIO will build project using “Debug” configuration even when you do not use PIO Unified Debugger.

Example of classic “release” and “debug” scheme using “platformio.ini” (Project Configuration File)

platform = ...
board = ...
framework = ...
targets = debug

platform = ...
board = ...
framework = ...
  • platformio run command builds ALL environments and places artifacts to build_dir
  • platformio run --environment debug builds only debug environment
  • platformio run --environment release builds only release environment.
  • platformio run --environment release --target upload builds project using “Release” configuration and upload firmware/artifacts to end device.

Please note that you can set a default build environment per a project using env_default option in Section [platformio].