platformio configuration file

platformio.ini (configuration file)

Each PlatformIO project has a configuration file named platformio.ini in the root directory for the project.
platformio.ini has sections (each denoted by a [header]) and key / value pairs within the sections. Lines beginning with ; are ignored and may be used to provide comments.
Multiple value options can be specified in two ways:

  1. Split values with “, ” (comma + space)
  2. Multi-line format, where each new line starts with at least two spaces

there are two main sections
1- PlatformIO Core (CLI) settings: Section [platformio]
2- Environment settings: Section [env]


description : Short description of the project

default_envs : The platformio run command processes all environments [env:***] by default if the platformio run --environment option is not specified. 

extra_configs : This option allows extending a base “platformio.ini” (Project Configuration File) with extra configuration files.

Base “platformio.ini”

description = this is new project 
default_envs = esp32dev
extra_configs =

; Global data for all [env:***]
platform = espressif32
framework = espidf

; Custom data group
; can be use in [env:***] via ${common.***}
debug_flags = -D RELEASE
lib_flags = -lc -lm

board = esp-wrover-kit
build_flags = ${common.debug_flags}


board = esp32dev
build_flags = ${common.lib_flags} ${common.debug_flags}

platform = espressif32
framework = espidf
board = lolin32
build_flags = ${common.debug_flags}

src_dir: The path to the project’s directory with source code. Default: “Project/src
lib_dir : You can put your own/private libraries here. The source code of each library should be placed in a separate directory Default: “Project/data

For example, see how the Foo and Bar libraries are organized:

|  |--Bar
|  |  |--docs
|  |  |--examples
|  |  |--src
|  |     |- Bar.c
|  |     |- Bar.h
|  |--Foo
|  |  |- Foo.c
|  |  |- Foo.h
|- platformio.ini
   |- main.c

Then in src/main.c you should use:

#include <Foo.h>
#include <Bar.h>


Each project may have multiple configuration environments defining the available project tasks for building, programming, debugging, unit testing, device monitoring, library dependencies, etc.

Common [env] : An optional configuration environment with common options that will be shared between all [env:NAME] environments in the platform.ini file.

platform = ststm32
framework = stm32cube
board = nucleo_l152re
lib_deps = Dep1, Dep2

build_flags = -D RELEASE
lib_deps =

build_type = debug
build_flags = -D DEBUG
lib_deps = DepCustom

Environment [env:NAME] : A section with an env: prefix defines a working environment for platformio runplatformio testplatformio checkplatformio debug and other commands. Multiple [env:NAME] environments with different NAME are allowed. Every project must define at least one working environment.
Each environment must have a unique NAME. The valid chars for NAME are letters a-z, numbers 0-9, special char _ (underscore). For example, [env:hello_world].

you can use options inside [env] the next link for all available options

Dynamic variables

Dynamic variables (interpolations) are useful when you have a custom configuration data between build environments. For examples, extra build_flags or project dependencies lib_deps.

Each variable should have a next format: ${<section>.<option>}, where <section> is a value from [<section>] group, and <option> is a first item from pair <option> = value.

You can inject system environment variable using sysenv as a section. For example, ${sysenv.HOME}.

  • Variable can be applied only for the option’s value
  • Multiple variables are allowed
  • The Section [platformio] and Section [env] sections are reserved and could not be used as a custom section. Some good section names might be extra or custom.
; Unix
lib_extra_dirs = ${sysenv.HOME}/Documents/Arduino/libraries
; Windows
lib_extra_dirs = ${sysenv.HOMEDRIVE}${sysenv.HOMEPATH}\Documents\Arduino\libraries

; You MUST inject these options into [env:] section
; using ${extra.***} (see below)
build_flags = -D VERSION=1.2.3 -D DEBUG=1
lib_deps_builtin =
lib_deps_external = ArduinoJson@>5.6.0

platform = atmelavr
framework = arduino
board = uno
build_flags = ${extra.build_flags}
lib_deps =

platform = espressif8266
framework = arduino
board = nodemcuv2
build_flags = ${extra.build_flags} -Wall
lib_deps =

; Keep sensitive data in environment variables
; Unix
; export WIFI_SSID='\"my\ ssid\ name\"'
; export WIFI_PASS='\"my\ password\"'
; Windows
; set WIFI_SSID='"my ssid name"'
; set WIFI_PASS='"my password"'

extends = env:nodemcuv2
platform = espressif32
board = esp32dev
build_flags =