pio-pkg

Create a package tarball from the current directory

$ pio pkg pack [[-o|--output]] [path/to/package.tar.gz]

$ pio pkg publish

$ pio pkg publish --private

$ pio pkg publish [path/to/package.tar.gz]

$ pio pkg publish [path/to/package.tar.gz] --released-at "[2021-04-08 21:15:38]"

$ pio pkg unpublish [package]

$ pio pkg unpublish [package]@[version]

$ pio pkg unpublish --undo [package]@[version]

pio pkg [options]
pio pkg install [options] []
pio pkg update [options] []
pio pkg uninstall [options] []
pio pkg list [options]
pio pkg search [options]
pio pkg pack [options]
pio pkg publish [options]

install
    Installs specified packages (libraries, platforms, toolchains, frameworks). Can be used without arguments within a project to install all dependencies from platformio.ini.

update
    Updates installed packages to their latest compatible versions. If no package is specified, all project or global packages are updated.

uninstall
    Removes specified packages from the system or project environment.

list
    Lists all currently installed packages, categorized by type (libraries, platforms, etc.).

search
    Searches the PlatformIO Registry for packages matching a given query.

pack
    Packs a local library into a distributable archive (.tar.gz) for publishing or local installation.

publish
    Publishes a packed library to the PlatformIO Registry, making it available for other developers.

-g, --global
    Applies the command to global packages rather than project-specific ones. Applicable to install, update, uninstall.

--library
    Specifies that the operation applies to a library package type.

--platform
    Specifies that the operation applies to a development platform package type.

--framework
    Specifies that the operation applies to a framework package type.

--toolchain
    Specifies that the operation applies to a toolchain package type.

--storage-dir
    Specifies a custom directory for package storage instead of the default location.

--save
    When installing a library, adds it to the lib_deps section of the project's platformio.ini file. Applicable to install.

--skip-dependencies
    Skips the installation of package dependencies. Applicable to install.

--json-output
    Outputs command results in JSON format, useful for scripting and programmatic access.

-v, --verbose
    Enables verbose output, displaying more detailed information during command execution.

The pio-pkg command is an essential component of the PlatformIO Core, serving as its powerful package manager. It provides a robust and streamlined way to manage all dependencies required for embedded development projects, including libraries, development platforms (e.g., Espressif 32, STM32), toolchains (compilers, debuggers), and frameworks (e.g., Arduino, ESP-IDF).

pio-pkg automates the process of finding, downloading, installing, updating, and uninstalling these crucial components, ensuring that your development environment is consistent and up-to-date. This eliminates the complexities of manual dependency management, allowing developers to focus on writing code for their embedded systems. It supports various package sources, including PlatformIO Registry, local paths, and VCS repositories, making it incredibly flexible for diverse project requirements. Its integration with the PlatformIO project structure and configuration files (like platformio.ini) ensures reproducible builds and simplifies collaboration among developers.

Requires PlatformIO Core to be installed on the system.
Many operations, especially install and update, require an active internet connection to download packages from the PlatformIO Registry or other remote sources.
Package versioning and compatibility can sometimes lead to conflicts, requiring manual resolution or specific version pinning in platformio.ini.

pio-pkg manages several distinct types of packages crucial for embedded development:
Libraries: Reusable code components (e.g., sensor drivers, communication protocols).
Development Platforms: Integrated environments for specific hardware architectures (e.g., Espressif 32, Atmel AVR), including SDKs, toolchains, and frameworks.
Toolchains: Collections of programming tools, primarily compilers, assemblers, and linkers, specific to a target architecture.
Frameworks: Software abstraction layers that simplify interaction with hardware, such as Arduino, ESP-IDF, Mbed OS.

Packages can be specified and managed within a PlatformIO project's platformio.ini configuration file. This allows for dependency declaration (e.g., lib_deps, platform, board) which pio-pkg install automatically resolves and installs when a project is initialized or built, ensuring reproducible builds across different development environments.

PlatformIO, including its package management capabilities, was created by Ivan Grytsenko and first released around 2014. It emerged as a comprehensive, open-source ecosystem designed to simplify cross-platform embedded development, addressing the fragmentation and complexity often found in this domain. The pio-pkg command became a central piece of PlatformIO's architecture, enabling developers to easily manage the vast and growing collection of hardware-specific libraries, development platforms, toolchains, and frameworks. Its continuous development has kept pace with new microcontrollers and development boards, establishing PlatformIO as a popular choice for professional and hobbyist embedded engineers.

pio(1), pip(1), npm(1), apt(8), dnf(8)