Custom options in platformio.ini

PlatformIO allows you extending project configuration with own data. Custom options have to start with custom_ or board_ to not generate a warning that the unknown configuration option will be ignored by PlatformIO. You can read these values later using ProjectConfig API:

ProjectConfig::get(section, option, default=None):

Get an option value for the named section


Returns a list of the sections available

ProjectConfig::items(section, as_dict=False):

Returns a list of “name”, “value” pairs for the options in the given section or a dictionary when as_dict=True is passed


Indicates whether the named section is present in the configuration

ProjectConfig::has_option(section, option):

If the given section exists, and contains the given option, returns True; otherwise returns False.

PlatformIO’s “ProjectConfig” is compatible with a native Python’s ConfigParser API.



hello = world

platform = ...
extra_scripts =

custom_option1 = value1
custom_option2 = value2

# "env.GetProjectOption" shortcut for the active environment
value1 = env.GetProjectOption("custom_option1")
value2 = env.GetProjectOption("custom_option2")

# Read value from other environments
config = env.GetProjectConfig()
world = config.get("universe", "hello")