# platformio lib install

Contents

- platformio lib install

  - Usage

  - Description

  - Storage Options

  - Options

  - Version control

    - Git

    - Mercurial

    - Subversion

  - Examples

## Usage

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

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

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

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

    # install to global storage
    platformio lib --global install [OPTIONS] [LIBRARY...]
    platformio lib -g install [OPTIONS] [LIBRARY...]

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

    # [LIBRARY...] forms
    platformio lib [STORAGE_OPTIONS] install (with no args, project dependencies)
    platformio lib [STORAGE_OPTIONS] install <id>
    platformio lib [STORAGE_OPTIONS] install id=<id>
    platformio lib [STORAGE_OPTIONS] install <id>@<version>
    platformio lib [STORAGE_OPTIONS] install <id>@<version range>
    platformio lib [STORAGE_OPTIONS] install <name>
    platformio lib [STORAGE_OPTIONS] install <name>@<version>
    platformio lib [STORAGE_OPTIONS] install <name>@<version range>
    platformio lib [STORAGE_OPTIONS] install <zip or tarball url>
    platformio lib [STORAGE_OPTIONS] install file://<zip or tarball file>
    platformio lib [STORAGE_OPTIONS] install file://<folder>
    platformio lib [STORAGE_OPTIONS] install <repository>
    platformio lib [STORAGE_OPTIONS] install <name>=<repository> (name it should have locally)
    platformio 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

- Atom: “Menu: PlatformIO > Rebuild C/C++ Project Index (Autocomplete, Linter)”

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

## Description

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

1. Library `id` or `name` from PlatformIO Library Registry

2. Custom folder, repository or archive.

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

- `1.2.3` - an exact version number. Use only this exact version

- `^1.2.3` - any compatible version (exact version for `1.x.x` versions)

- `~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`

PlatformIO supports installing from local directory or archive. Need to use `file://` prefix before local path. Also, directory or archive should contain `.library.json` manifest (see library.json).

- `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 Library Manager CLI.

## Options

--save

Save installed libraries into the “platformio.ini” (Project Configuration File) dependency list (lib_deps).

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

-s, --silent

Suppress progress reporting

--interactive

Allow one to make a choice for all prompts

-f, --force

Reinstall/redownload library if it exists

## 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:

- user/library (short version for GitHub repository)

- 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

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

    > platformio 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
    > platformio 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

2. Install specified version of a library to a global storage

    > platformio 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!

3. Install library with dependencies to custom storage

    > platformio 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!

4. Install ARM mbed library to the global storage

    > platformio 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!

5. Install from archive using URL

    > platformio 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!