PIO library doesn't see header files in project's include folder

It happened to me now several times, that a library needs a configuration file in order to work. This file has to be created by user and it’s not included in the library itself.

The problem is, that PlatformIO doesn’t see header files that are referenced by the library, but are present in the projects include folder. This has happened to me at least with uGFX library , STEmWin and now with FatFS library.

I tried adding the path to my project’s ‘include’ folder via build_flags. It then moved forward, but stuck again when a library was referencing files, which were either:

  • added into the project with lib_extra_dirs
  • part of the framework

The only thing that worked for me, was adding paths to each individual folder with build_flags = -I/path_to_folder/. But that is not a long-term solution and impossible to do with larger/complex libs.

So always when library wants to reference anything outside it, build process crashes. Can someone confirm that it’s the PlatformIO problem?

I am having the exact same problem. Did you ever solve it?

Could you provide a simple project to reproduce this issue?

I am unable to produce the exact issue I have right now in a simple project, but I found a similar issue with co-dependent libraries. Here is the example project file structure:


Include.h —
#pragma once
#include <Lib.h>

Lib.h —
#pragma once
#include <Include.h>

Lib.cpp —
#include “Lib.h”

Include.cpp —
#include <Include.h>

main.cpp —
#include <Arduino.h>
#include <Include.h>
void setup() {}
void loop() {}

When I try to build I get this:

Processing uno (platform: atmelavr; board: uno; framework: arduino)

Verbose mode can be enabled via -v, --verbose option
CONFIGURATION: Redirecting...
PLATFORM: Atmel AVR 1.15.0 > Arduino Uno
HARDWARE: ATMEGA328P 16MHz, 2KB RAM, 31.50KB Flash
PACKAGES: toolchain-atmelavr 1.50400.190710 (5.4.0), framework-arduinoavr 4.1.2
LDF: Library Dependency Finder → Library Dependency Finder (LDF) — PlatformIO latest documentation
LDF Modes: Finder ~ chain, Compatibility ~ soft
Found 6 compatible libraries
Scanning dependencies…
Dependency Graph
Compiling .pio\build\uno\lib919\Lib\Lib.cpp.o
In file included from lib\Lib\Lib.cpp:1:0:
lib\Lib\Lib.h:2:21: fatal error: Include.h: No such file or directory

  • Looking for Include.h dependency? Check our library registry!
  • CLI > platformio lib search “header:Include.h”
  • Web > PlatformIO Registry

compilation terminated.
*** [.pio\build\uno\lib919\Lib\Lib.cpp.o] Error 1
============================ [FAILED] Took 0.83 seconds ============================
The terminal process terminated with exit code: 1

Terminal will be reused by tasks, press any key to close it.

@ivankravets Here is an example that illustrates how including a header file from include/ in a file placed inside lib/xxx/ leads to an error.

Project files:

  • include/define.h
  • platformio.ini
  • lib/average/average.h
  • lib/average/average.cpp
  • src/main.cpp


#define ANALOG_PIN A0


#include <Arduino.h>
#include <define.h>

double average(void);


#include <average.h>

double average(void) {
    uint64_t accu = 0U;
    for (uint32_t i = 0U; i < 1000; ++i) {
        accu += analogRead(ANALOG_PIN);
    double average = (static_cast<double>(accu) / 1000);
    return average;


#include <average.h>

void setup() {
  // Start serial console
  Serial.println("Average: ");

void loop() {


platform = espressif8266
board = nodemcuv2
framework = arduino


In file included from lib/average/average.cpp:1:0:
lib/average/average.h:2:20: fatal error: define.h: No such file or directory

* Looking for define.h dependency? Check our library registry!
* CLI  > platformio lib search "header:define.h"
* Web  > https://platformio.org/lib/search?query=header:define.h

 #include <define.h>
1 Like

I have exactly the same problem. I thought that the include directory would be the place to put “global” include files, however that doesn’t seem to work. What is the way to do this?

Any one has fixed this issue.?

That’s intentional, include and src folders are not global and only visible to project sources (not libraries or frameworks). If you need this include globally specify it in build_flags:

build_flags = -I include

Can anyone explain to a newbie where to add this build_flags = -I include ??
I have a main.cpp and a separate header file in the include directly. I installed VS PlatformIO on a new PC and downloaded repository and the include files are not recognized in my main.cpp file.
Appreciate any assistance!

As per available online documentation, build_flags is a configuration option in the platformio.ini file of the project.

Thank you Max for super fast response. I have added build_flags = -I to platform.ini as advised, but still I get red squiggles under these
#include <Arduino.h>
#include <NTPClient.h>
#include <WiFiUdp.h>
#include <time.h>
#include <wifi.h>
#include <LiquidCrystal_I2C.h>
#include <HTTPClient.h>
#include “Keypad.h”

which reside in include directory.
When I try to build I get this error:-
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------C:\Users\pfren.platformio\python3\python.exe: can’t open file ‘C:\Users\pfren.platformio\packages\tool-scons\scons.py’: [Errno 2] No such file or directory

This is a new installation, any idea what else I may need to do?
Thanks again,

After the -I must be the path that you want to add to the include path for compilation, if you just write this it’s empty.

Try and correct the platformio.ini per above but if that doesn’t work, it seems like a different issue entirely: Like SCons is missing. If that’s the case, remove the folder C:\Users\pfren\.platformio\packages\tool-scons\ and retry building.

Max - thanks again for your assistance. I apologize for being so new to this, but what path do I need? Is it a folder on my pc or in Git or within platformio itself?
Is it like this?

platform = espressif32

board = esp32dev

framework = arduino

monitor_speed = 115200

monitor_filters = log2file

build_flags = -I icmsteep.h

lib_deps =


C:\Users\User 1\OneDrive\Documents\PlatformIO\Projects\ICM Steep Tank\lib\LiquidCrystal_I2C


Where is this file located? The path must be relative to the root of the project. (You can also use absolute path but this makes the project non-portable for other computers)

If you place the icmsteep.h e.g. in the include/ folder of the project, you must add build_flags = -I include to the platformio.ini so that the include folder is added for lookup.

I am having the same problem. If you read the “readme” files in the “lib” and “library” folders you’d think this functionality would work. We are doing it according to the readme so why doesn’t this work?

I am trying to include my project library files in the include folder and it’s not working. I get linking errors. I look at .json configuration and it includes the include path but for some reason the complier cannot figure it out.

I’d think the whole reason for an IDE would be so you don’t have to hack this stuff… Is this a bug? Is there a fix?

.json configuations include path includes the include folder. It has the correct absolute path. However, I don’t believe the compiler is finding the object files?

Here’s a screen capture of my issue