pio pkg install

New in version 6.0.

Contents

• pio pkg install

  • Usage

  • Description

  • Options

  • Package Types

  • Package Specifications

    • Registry: Latest Version

    • Registry: Specific Version

    • Registry: Version Requirements

    • Repository (git, hg, svn)

    • Local Folder

    • Local TAR or ZIP archive

    • Remote TAR or ZIP archive

  • Version Requirements

  • See Also

Usage

pio pkg install [OPTIONS]

Description

Install the project dependencies or custom packages from the PIO Registry or external sources.

If no custom packages (--library, --platform, or --tool) are specified, the command will install the following project dependencies based on “platformio.ini” (Project Configuration File):

• Library dependencies declared using the lib_deps option

• Development platform declared using the platform option and its dependencies (toolchain, framework, SDKs, debugging server, etc)

• Custom tools declared using the platform_packages option.

Options

-d, --project-dir

Specify the path to project directory. By default, --project-dir is equal to current working directory (CWD).

-e, --environment

Install project dependencies only for the specified environments. Multiple environments are allowed.

-p, --platform

Install specified development platform using Package Specifications. Multiple items are allowed.

Examples

pio pkg install -p "aceinna/aceinna_imu@^1.3.8" -p "platformio/atmelavr"
pio pkg install --platform "https://github.com/platformio/platform-sifive.git"

-t, --tool

Install specified tool using Package Specifications. Multiple items are allowed.

Examples

pio pkg install -t "platformio/tool-openocd"
pio pkg install --tool https://github.com/platformio/platform-sifive.git

-l, --library

Install specified library using Package Specifications. Multiple items are allowed.

Examples

pio pkg install -l "bblanchon/ArduinoJson@^6.19.2" -l "milesburton/DallasTemperature@^3.9.1"
pio pkg install --library https://github.com/Makuna/NeoPixelBus.git

--no-save

Prevent saving specified packages to “platformio.ini” (Project Configuration File).

--skip-dependencies

Install a package but skip its dependencies declared in the manifest dependencies field.

-g, --global

Warning

We DO NOT recommend installing libraries in the global storage. Please use the lib_deps option and declare library dependencies per project.

Install packages to the global storage:

• platforms_dir - development platforms

• packages_dir - tools

• globallib_dir - libraries.

A package installed to the global storage will be available for any PIO project.

--storage-dir

Specify a custom Package Manager storage for global packages.

-f, --force

Reinstall a package if exists. The existing package will be removed and the latest compatible version will be installed.

-s, --silent

Suppress progress reporting.

Package Types

PIO supports the next package types:

library

The Assembly/C/C++ files that can extend project functionality

platform

See Platforms for details

tool

A specialized program, toolchain, or source of auxiliary files (framework, SDK) that are used to build a project, debug it or upload firmware to the target device.

Browse over 10,000 packages in the PIO Registry.

Package Specifications

PIO supports different package sources which you can specify for pio pkg install command or configure project dependencies using “platformio.ini” (Project Configuration File) options:

• platform - development platform

• platform_packages - custom tools/packages

• lib_deps - libraries.

A package is:

1. A folder containing manifest file (library.json, platform.json or package.json)

2. TAR or ZIP archive containing (a)

3. A URL that resolves to (b)

4. An <owner>/<name>@<version requirements> that is published on the PIO Registry

5. A <git/hg/svn remote url> that resolves to (a).

Registry: Latest Version

Specification: <owner>/<name>

Install the latest package version from the PIO Registry.

Tip

We highly recommend prefixing a version with ^ (caret) symbol which will instruct PIO to install the latest compatible version avoiding breaking changes in the future. See Version Requirements for details.

Examples

1. Install ArduinoJson and Embedded Template libraries, and add them to the project dependencies (lib_deps):

   pio pkg install --library "bblanchon/ArduinoJson" --library "etlcpp/Embedded Template Library"
   

2. Declare ArduinoJson and Embedded Template libraries as the project dependencies using lib_deps configuration option:

   [env:myenv]
   lib_deps =
       bblanchon/ArduinoJson
       etlcpp/Embedded Template Library
   

3. Install SEGGER J-Link Software for debug probes:

   pio pkg install --tool "platformio/tool-jlink"
   

Registry: Specific Version

Specification: <owner>/<name>@<version>

Install the specified version of a package from the PIO Registry. This will fail if the version has not been published to the registry.

Example

bblanchon/ArduinoJson@6.9.12

Registry: Version Requirements

Specification: <owner>/<name>@<version requirements>

Install the latest version of a package from the PIO Registry matching the specified version requirements. See Version Requirements for details.

Example

bblanchon/ArduinoJson@>=6,!=6.13.0

Repository (git, hg, svn)

Specification: [<name>=][<scheme>://][<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish|branch|tag>]

Install the package at the specified URL by attempting to clone it. If the repository makes use of submodules, those submodules will be cloned as well.

The supported schemes are:

• http

• https

• git

• git+http

• git+https

• git+ssh

• hg+http

• hg+https

• hg+ssh

• svn+http

• svn+https

• svn+ssh

You can override a package folder name in the Package Manager storage using the <name>= syntax. See the example below.

Examples

1. Clone default branch of Github repository using HTTPS

   https://github.com/platformio/platform-espressif32.git
   

2. Clone default branch of Github repository using SSH

   git@github.com:platformio/platform-espressif32.git
   
   # or
   
   git+username@github.com:platformio/platform-espressif32.git
   

3. Clone Git repository using SSH and custom username

   git+ssh://git.server.org/my-platform
   
   # or
   
   git+ssh://user@git.server.org/my-platform
   

4. Clone “master” branch of Git repository

   https://github.com/platformio/platform-espressif32.git#master
   

5. Clone “v3.3.0” tag of Git repository

   https://github.com/platformio/platform-espressif32.git#v3.3.0
   

6. Clone specified commit of Git repository

   https://github.com/platformio/platform-espressif32.git#084131f6634c818485781651d76818cd1f13a461
   

7. Clone specified commit of Git repository and set custom package folder name to “ESP32”

   ESP32=https://github.com/platformio/platform-espressif32.git#084131f6634c818485781651d76818cd1f13a461
   

8. Clone Mercurial repository

   hg+hg://hg.server.org/my-package
   hg+https://hg.server.org/my-package
   hg+ssh://hg.server.org/my-package
   

Local Folder

Specification	Description
[<name>=]file://<folder>	Copy all files from the local folder to the Package Manager. Making changes in the source folder WILL NOT affect the installed package.
[<name>=]symlink://<folder>	Create a symbolic link pointing the local source folder to the Package Manager. Making changes in the source folder WILL affect the installed package.

Install a package and its dependencies from a local folder. A path should start with file:// or symlink:// prefix and the package folder must contain a manifest file (library.json, platform.json, or package.json) with name and version properties.

You can override a package folder name in the Package Manager storage using the <name>= syntax. See the example below.

Examples

# Unix, hard copying
file:///local/path/to/the/package/dir

# Windows, symbolic link
symlink://C:/local/path/to/the/package/dir

# Custom package folder name "SomeLib" in the storage
SomeLib=file:///local/path/to/the/package/dir

Local TAR or ZIP archive

Specification: [<name>=]file://<tar or zip file>

Install a package and its dependencies from a local TAR or ZIP archive.

Archive requirements:

• the filename must use .tar.gz, .tar, .tgz, or .zip as the extension

• the package must contain a manifest file (library.json, platform.json, or package.json) with name and version properties.

You can override a package folder name in the Package Manager storage using the <name>= syntax. See the example below.

Examples

# tar.gz
file:///local/path/to/the/archive.tar.gz

# zip
file:///local/path/to/the/archive.zip

# Custom package folder name "SomeLib" in the storage
SomeLib=file:///local/path/to/the/archive.tar.gz

Remote TAR or ZIP archive

Specification: [<name>=]<archive url>

Fetch the archive URL, and then install a package and its dependencies. The URL must start with http:// or https://.

You can override a package folder name in the Package Manager storage using the <name>= syntax. See the example below.

Examples

# TAR archive
https://github.com/bblanchon/ArduinoJson/archive/refs/heads/6.x.tar.gz

# ZIP archive
https://github.com/bblanchon/ArduinoJson/archive/refs/heads/6.x.zip

# Custom package folder name "JSON" in the storage
JSON=https://github.com/bblanchon/ArduinoJson/archive/refs/heads/6.x.tar.gz

Version Requirements

Note

PIO uses python-semanticversion library to handle SemVer versions and specifications.

The @<version requirements> specification supports Semantic Versioning ( <MAJOR>.<MINOR>.<PATCH>):

• MAJOR - incompatible API changes

• MINOR - add functionality (backwards-compatible)

• PATCH - bug fixes (backwards-compatible).

The version requirements can take any of the following forms (see Semver cheatsheet):

• ^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.

To list available package versions and installation instructions, please visit the PIO Registry.

Example:

Depend on the platformio/espressif32 development platform with the next requirements:

• version is >=3.5.0

• version is <4.0.0

• version is not 3.2.0

platformio/espressif32@>=3.5.0,<4,!=3.2.0

# or short form
platformio/espressif32@^3.5.0,!=3.2.0

See Also

• pio pkg uninstall

• pio pkg outdated

• library.json