PlatformIO Community

Development libraries -- how to include in a project?

I’m coming from the Arduino IDE, so bear with me…

Let’s say I have a project that relies on a packaged library – let’s say an IMU library from one of the usual suspects (e.g., SF, Pololu, etc.). I want to modify the library to add functionality to it, and I want that to be available to other projects, as well.

So, I first fork the library on github. Then I include it in my lib_deps:

lib_deps =

platformio now makes a local copy in my project tree, yes? I can edit the code, but it doesn’t appear to be under git, so changes that I make are not pushed back to my repo. Worse, I make another project, and it makes its own copy, so now things are getting out of control.

I did have a couple of libraries in the global lib, but now they won’t update. I get the error discussed here:, which seems to imply that if I make changes to a cloned repo, it breaks things (which makes no sense to me – I want to be able to update the libraries!).

So, what should I do? Where should I put libraries that are under development so that

a) I can use the changes in multiple projects (preferably wo/ having to update everything from project to project), and
b) I can use git to manage them

Happy to answer questions. Hard to explain when I don’t know much of the basics.

There are mainly three options:

  • Put it in the global ~/.platformio/lib directory. Of course, it won’t update automatically anymore.
  • Put them in a directory outside ~/.platformio and outside your project folder and refer to the directory (or rather the parent directory) using lib_extra_dirs. Again, no automatic update.
  • Put them into the lib directory within your project folder. This approach is useful if the modification is for a single project only. No automatic update either.

Don’t make changes to the code in .pio/libdeps/.... .pio is just a temporary directory. I often delete it to force a clean build.

Automatic updates for modified libraries are not possible. It is not a restriction of PlatformIO but rather an inherent restriction of two source code copies that are independently modified. What should happen if the original maintainer changes the same line of code as you did? Should your change be overwritten? Or should it have priority over the other change? Or should both lines of code be used? In what order? Only you can tell.

In order to keep up with the latest changes of the library, use git tools. In many cases, you will be able to pull the latest changes and merge them automatically. In case of conflicts, you will have to merge them manually.

Thanks for the summary. That helps.

I didn’t think of this – thanks for the warning.