pio lib install ¶

Usage ¶

pio lib [STORAGE_OPTIONS] install [OPTIONS] [LIBRARY...]

# RECOMMENDED
# install all project dependencies declared via "lib_deps"
# (run it from a project root where is located "platformio.ini")
pio lib install [OPTIONS]

# install project dependent library
# (run it from a project root where is located "platformio.ini")
pio lib install [OPTIONS] [LIBRARY...]

# install dependencies for the specific project environment
# (run it from a project root where is located "platformio.ini")
pio lib -e myenv install [OPTIONS] [LIBRARY...]
pio lib -d /path/to/platformio/project -e myenv install [OPTIONS] [LIBRARY...]

# install to global storage (NOT RECOMMENDED)
pio lib --global install [OPTIONS] [LIBRARY...]
pio lib -g install [OPTIONS] [LIBRARY...]

# install to custom storage
pio lib --storage-dir /path/to/dir install [OPTIONS] [LIBRARY...]
pio lib -d /path/to/dir1 -d /path/to/dir2 install [OPTIONS] [LIBRARY...]

# [LIBRARY...] forms
pio lib [STORAGE_OPTIONS] install (with no args, install project dependencies from "lib_deps")
pio lib [STORAGE_OPTIONS] install <ownername/name>
pio lib [STORAGE_OPTIONS] install <ownername/name>@<version>
pio lib [STORAGE_OPTIONS] install <ownername/name>@<version range>
pio lib [STORAGE_OPTIONS] install <zip or tarball url>
pio lib [STORAGE_OPTIONS] install file://<zip or tarball file>
pio lib [STORAGE_OPTIONS] install file://<folder>
pio lib [STORAGE_OPTIONS] install <repository>
pio lib [STORAGE_OPTIONS] install <name>=<repository> (name it should have locally)
pio lib [STORAGE_OPTIONS] install <repository#tag> ("tag" can be commit, branch or tag)

Warning

If some libraries are not visible in PlatformIO IDE and Code Completion or Code Linting does not work properly, please perform

VSCode: “Menu: View > Command Palette… > PlatformIO: Rebuild C/C++ Project Index”

Description ¶

Install a library, and any libraries that it depends on using:

PlatformIO Library Registry
Custom folder, repository or archive.

The version supports Semantic Versioning ( <major>.<minor>.<patch>) and can take any of the following forms:

^1.2.3 - any compatible version (new functionality in a backwards compatible manner and patches are allowed, 1.x.x). RECOMMENDED
~1.2.3 - any version with the same major and minor versions, and an equal or greater patch version
>1.2.3 - any version greater than 1.2.3. >=, <, and <= are also possible
>0.1.0,!=0.2.0,<0.3.0 - any version greater than 0.1.0, not equal to 0.2.0 and less than 0.3.0
1.2.3 - an exact version number. Use only this exact version.

PlatformIO supports installing from local directory or archive. YOu need to use file:// prefix before local path.

file:///local/path/to/the/platform/dir
file:///local/path/to/the/platform.zip
file:///local/path/to/the/platform.tar.gz

Storage Options ¶

See base options for pio lib.

Options ¶

--save / --no-save¶

Save installed libraries into the “platformio.ini” (Project Configuration File) dependency list (lib_deps). Default value is to save.

You can save libraries for the specific project environment using -e, --environment option from pio lib command. For example, pio lib -e myenv install [LIBRARY...].

-s, --silent¶

Suppress progress reporting.

-f, --force¶

Reinstall library if it is already installed.

Version control ¶

PlatformIO supports installing from Git, Mercurial and Subversion, and detects the type of VCS using url prefixes: “git+”, “hg+”, or “svn+”.

Note

PlatformIO requires a working VCS command on your path: git, hg or svn.

Git ¶

The supported schemes are: git, git+https and git+ssh. Here are the supported forms:

https://github.com/user/library.git
git+git://git.server.org/my-library
git+https://git.server.org/my-library
git+ssh://git.server.org/my-library
git+ssh://user@git.server.org/my-library
[user@]host.xz:path/to/repo.git

Passing branch names, a commit hash or a tag name is possible like so:

https://github.com/user/library.git#master
git+git://git.server.org/my-library#master
git+https://git.server.org/my-library#v1.0
git+ssh://git.server.org/my-library#7846d8ad52f983f2f2887bdc0f073fe9755a806d

Mercurial ¶

The supported schemes are: hg+http, hg+https and hg+ssh. Here are the supported forms:

https://developer.mbed.org/users/user/code/library/ (install ARM mbed library)
hg+hg://hg.server.org/my-library
hg+https://hg.server.org/my-library
hg+ssh://hg.server.org/my-library

Passing branch names, a commit hash or a tag name is possible like so:

hg+hg://hg.server.org/my-library#master
hg+https://hg.server.org/my-library#v1.0
hg+ssh://hg.server.org/my-library#4cfe2fa00668

Subversion ¶

The supported schemes are: svn, svn+svn, svn+http, svn+https and svn+ssh. Here are the supported forms:

svn+svn://svn.server.org/my-library
svn+https://svn.server.org/my-library
svn+ssh://svn.server.org/my-library

You can also give specific revisions to an SVN URL, like so:

svn+svn://svn.server.org/my-library#13

Examples ¶

Install the latest version of library to a global storage using ID or NAME

> pio lib -g install 4

Library Storage: /storage/dir/...
LibraryManager: Installing id=4
Downloading  [####################################]  100%
Unpacking  [####################################]  100%
IRremote @ 2.2.1 has been successfully installed!

# repeat command with name
> pio lib -g install IRRemote

Library Storage: /storage/dir/...
Looking for IRRemote library in registry
Found: https://platformio.org/lib/show/4/IRremote
LibraryManager: Installing id=4
IRremote @ 2.2.1 is already installed

Install specified version of a library to a global storage

> pio lib -g install ArduinoJson@5.6.7

Library Storage: /storage/dir/...
Looking for ArduinoJson library in registry
Found: https://platformio.org/lib/show/64/ArduinoJson
LibraryManager: Installing id=64 @ 5.6.7
Downloading  [####################################]  100%
Unpacking  [####################################]  100%
ArduinoJson @ 5.6.7 has been successfully installed!

Install library with dependencies to custom storage

> pio lib --storage-dir /my/storage/dir install DallasTemperature

Library Storage: /my/storage/dir
Looking for DallasTemperature library in registry
Found: https://platformio.org/lib/show/54/DallasTemperature
LibraryManager: Installing id=54
Downloading  [####################################]  100%
Unpacking  [####################################]  100%
DallasTemperature @ 3.7.7 has been successfully installed!
Installing dependencies
Looking for OneWire library in registry
Found: https://platformio.org/lib/show/1/OneWire
LibraryManager: Installing id=1
Downloading  [####################################]  100%
Unpacking  [####################################]  100%
OneWire @ 8fd2ebfec7 has been successfully installed!

Install ARM mbed library to the global storage

> pio lib -g install https://developer.mbed.org/users/simon/code/TextLCD/

Library Storage: /storage/dir/...
LibraryManager: Installing TextLCD
Mercurial Distributed SCM (version 3.8.4)
(see https://mercurial-scm.org for more information)

Copyright (C) 2005-2016 Matt Mackall and others
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
requesting all changes
adding changesets
adding manifests
adding file changes
added 9 changesets with 18 changes to 6 files
updating to branch default
2 files updated, 0 files merged, 0 files removed, 0 files unresolved
TextLCD @ 308d188a2d3a has been successfully installed!

Install from archive using URL

> pio lib -g install  https://github.com/adafruit/DHT-sensor-library/archive/master.zip

Library Storage: /storage/dir/...
LibraryManager: Installing master
Downloading  [####################################]  100%
Unpacking  [####################################]  100%
DHT sensor library @ 1.2.3 has been successfully installed!