Managing Arduino Libraries in PlatformIO

If you’ve used the Arduino IDE, you know the routine: find a ZIP file, install it through “Sketch > Include Library,” and hope it works. While this is fine for small sketches, it quickly becomes frustrating as projects grow or when sharing code with collaborators.

PlatformIO offers a modern alternative: managing libraries directly inside your project using the lib_deps option in platformio.ini. This approach makes builds reproducible, keeps libraries organized, and avoids the need to copy ZIP files manually.

In this post, we’ll see why this method is better, how to install libraries using both the PlatformIO extension and manually editing platformio.ini, and finish with a complete example using the popular Adafruit SSD1306 display library.

Why lib_deps beats manual installs

Traditional manual installation in Arduino IDE:

• Download ZIP file → extract → install
• Re-do for every new machine
• Hard to track which version you used
• Collaborators might miss a library or install a different one

PlatformIO’s lib_deps:

• Declare your libraries in platformio.ini
• PlatformIO automatically installs them when you build
• Exact versions can be pinned
• Anyone cloning your repository can build it immediately

Installing libraries with the PlatformIO VS Code extension

If you’re using VS Code with the PlatformIO extension, adding libraries is very straightforward:

1. Open your project in VS Code.
2. Click on the PlatformIO icon in the Activity Bar on the left.
3. Go to Libraries.
4. Search for the library you want (e.g., “Adafruit SSD1306”).

5. Click Add to Project, and select your environment (e.g., env:uno).

This updates your platformio.ini automatically by adding:

lib_deps = adafruit/Adafruit SSD1306

The library is also downloaded from the platformIO registry and saved to .pio folder.

You can now use the library right away in your code.

Installing manually by editing platformio.ini

If you prefer, you can edit your platformio.ini file directly. For example:

[env:uno]
platform = atmelavr
board = uno
framework = arduino

lib_deps = adafruit/Adafruit SSD1306

This tells PlatformIO to download and install the Adafruit SSD1306 library when you build.

Using the library in your code

After adding to lib_deps and building the project, use the library like this:

src/main.cpp:

#include <Arduino.h>
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64

Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, -1);

void setup() {
    Serial.begin(115200);

    if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
        Serial.println(F("SSD1306 allocation failed"));
        for (;;); // Halt
    }

    display.clearDisplay();
    display.setTextSize(1);
    display.setTextColor(SSD1306_WHITE);
    display.setCursor(0,0);
    display.println(F("Hello, PlatformIO!"));
    display.display();
}

void loop() {
    display.clearDisplay();
    display.setCursor(0,0);
    display.println(millis() / 1000); // Show elapsed seconds
    display.display();
    delay(1000);
}

Build the project (PlatformIO: Build) and upload — you should see text on the display.

Pinning versions and adding more libraries

You can lock to specific versions for stability:

lib_deps =
    adafruit/Adafruit SSD1306@^2.4.7

Or add custom libraries by Git URL:

lib_deps = https://github.com/yourusername/YourLibrary.git

Summary

Manually installing libraries from ZIP files can become error-prone and hard to maintain. With PlatformIO, you simply declare dependencies once in platformio.ini (using either the VS Code extension or manual editing). PlatformIO keeps your environment reproducible, helps share projects easily, and handles updates consistently.

Using the lib_deps method, your projects stay organized and ready to build on any machine without extra setup.