Dependency Management¶

Library Registry¶

PlatformIO Registry contains a rich set of popular libraries with examples and instructions on how to add them to your project. Libraries in PlatformIO are isolated between projects and project environments. This helps you to avoid conflicts or break existing projects when you update libraries to the newest versions.

If you prefer using PlatformIO Core (CLI) instead of web browsing, the pio pkg search command allows you to search for libraries matching the search query.

Library sources¶

PlatformIO supports different library sources which you can use for declaring dependencies. The most popular are:

• Versioned libraries from PlatformIO Registry

• VCS repositories (Git, Hg, SVN)

• Remote or local library as a TAR or ZIP archive

• Local library as a source folder.

Dependency specifications¶

Please check Package Specifications for the available options.

Declaring dependencies¶

“platformio.ini” (Project Configuration File) and the lib_deps is the only place for declaring project dependencies. There are 2 sections where dependencies can be declared:

1. Section [env] - declare common dependencies for all environments

2. Working [env:NAME] - declare specific dependencies for the working environment.

Please take a look at the example below. The dep_1 and dep_2 dependencies are common to the release and debug working environments, whereas the dep_3 is a specific only for the debug working environment. The [env:debug] section overrides common lib_deps option, and the ${env.lib_deps} (Interpolation of Values technic) is used to merge the common and custom dependencies.

; Common dependencies declared in the common "[env]" section
[env]
platform = ...
board = ...
framework = ...
lib_deps =
  dep_1
  dep_2

[env:release]
build_flags = -D RELEASE=1

; Specific dependencies that extend the common dependencies
[env:debug]
lib_deps =
  ${env.lib_deps}
  dep_3

Declaring practices¶

[env:myenv]
lib_deps =
  ; Depend on the latest 6.x stable version of ArduinoJson.
  ; The minimum required version is 6.19.4.
  ; New functionality (backward-compatible) and bug-fixed are allowed
  bblanchon/ArduinoJson @ ^6.19.4

  ; Depend on the exact 1.1.1 version
  ; No new functionality (backward-compatible) or bug fixes.
  ; Recommended for safety-critical projects
  me-no-dev/AsyncTCP @ 1.1.1

  ; Depend on the particular tag (v2.13) of a Git repository
  https://github.com/username/HelloWorld.git#v2.13

[env:myenv]
lib_deps =
  ; Omit library package owner (<owner>/<name>) and depend on the library by name.
  ; Lead to the conflicts when there are multiple libraries with the same name
  OneWire

  ; Depend on ANY/Latest version of the development platform
  ; allowing breaking changes
  me-no-dev/AsyncTCP

  ; Depend on the development branch of the Git repository,
  ; allow breaking changes, and untested commits
  https://github.com/username/HelloWorld.git

Installing dependencies¶

PlatformIO automatically resolves and installs project dependencies when you build, debug, or test a project. If you want to install project dependencies manually, please use PlatformIO Core (CLI) and the pio pkg install command.

Updating dependencies¶

PlatformIO does not update project dependencies automatically. You need to use PlatformIO Core (CLI) and the pio pkg update command to update all project dependencies or for the specified environment. It is also possible to update the specified dependency.

We recommend using the pio pkg outdated command, checking available updates, and avoiding versions that introduce breaking changes.