Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
This quickstart demonstrates how to programmatically interact with PlatformIO Core CLI from Python. It initializes a new PlatformIO project for an `esp32dev` board and then lists the packages installed for that project. This interaction pattern is common for integrating PlatformIO into automation scripts or custom applications, as PlatformIO's primary interface is its command-line tool (`pio`). Ensure 'pio' is in your system's PATH.
import subprocess
import os
# Create a dummy project directory
project_dir = "my_pio_project"
os.makedirs(project_dir, exist_ok=True)
os.chdir(project_dir)
try:
# Initialize a PlatformIO project for a common board (e.g., esp32dev)
# This will download necessary frameworks and tools into the project's .pio folder
print(f"Initializing PlatformIO project in {os.getcwd()}...")
result = subprocess.run(
["pio", "project", "init", "--board", "esp32dev"],
capture_output=True, text=True, check=True
)
print("\n--- pio project init Output ---")
print(result.stdout)
if result.stderr:
print("\n--- pio project init Errors ---")
print(result.stderr)
# List installed packages within the project
print("\nListing installed packages...")
result = subprocess.run(
["pio", "pkg", "list"],
capture_output=True, text=True, check=True
)
print("\n--- pio pkg list Output ---")
print(result.stdout)
except subprocess.CalledProcessError as e:
print(f"Error executing PlatformIO command: {e}")
print(f"Stdout: {e.stdout}")
print(f"Stderr: {e.stderr}")
except FileNotFoundError:
print("Error: 'pio' command not found. Ensure PlatformIO Core CLI is installed and in your PATH.")
finally:
# Clean up the created project directory
os.chdir("..")
# In a real scenario, you might want to remove the directory:
# import shutil
# shutil.rmtree(project_dir)
print(f"\nQuickstart finished. Project directory: {project_dir}")
pio --version
Debug
Known issues
breakingPlatformIO Core 6.0 introduced a unified Package Management CLI (`pio pkg`), deprecating older commands like `pio lib`, `pio platform`, and `pio update`. Scripts or configurations relying on these older commands will break.fixMigrate to the new `pio pkg` commands. For example, use `pio pkg install` instead of `pio lib install` or `pio platform install`. Review the PlatformIO 6.0 Migration Guide.
affects: 6.0.0 and newer
gotchaHaving multiple PlatformIO Core installations or conflicting Python interpreters (especially on Windows) can lead to various issues, including `ImportError` or `pio` command not being recognized.fixFor VSCode IDE users, enable 'Use built-in PlatformIO Core' in settings. For standalone users, ensure only one instance of PlatformIO Core is installed, preferably using the recommended installer script which uses an isolated virtual environment. Uninstall obsolete Python interpreters and PlatformIO cores if necessary.
affects: All versions
gotchaPlatformIO Core (CLI) does not support projects with non-ASCII characters in their full path or in library names, leading to `UnicodeDecodeError` during compilation or `UnicodeWarning`.fixEnsure all project folders and source files are located in paths that contain only ASCII characters. Avoid using non-ASCII characters in project names or directory structures.
affects: All versions
gotchaAntivirus software can interfere with PlatformIO's background operations (e.g., downloading and unpacking packages), resulting in 'Access is denied' errors.fixTemporarily disable your antivirus, or add the PlatformIO Core directory (`~/.platformio` on Unix, `C:\Users\YourUserName\.platformio` on Windows) to your antivirus's exclusion/whitelist. Running `pio` commands from a system terminal might also bypass some antivirus blocks.
affects: All versions
gotchaNot explicitly defining platform and library versions in `platformio.ini` (e.g., `platform = espressif32` instead of `platform = espressif32@^6.10.0`) can lead to projects breaking with future updates of platforms or libraries.fixAlways use Semantic Versioning Requirements (`@^x.y.z`, `@~x.y.z`, etc.) for `platform` and `lib_deps` in your `platformio.ini` to ensure project reproducibility and stability over time.
affects: All versions, especially with Core 6.0's declarative approach emphasis
Errors
Common errors & fixes
Error: Please specify `upload_port` for environment or use global `--upload-port` option.
PlatformIO cannot automatically detect the serial port to use for uploading the firmware to your board.
fixAdd `upload_port = COMx` (Windows) or `upload_port = /dev/ttyUSBx` (Linux/macOS) to your `platformio.ini` file under the specific environment, or manually specify it using `pio run --target upload --upload-port COMx` in the CLI.
fatal error: SomeLibrary.h: No such file or directory.
The compiler cannot find an included library header file, typically because the library is not installed, or its path is not correctly specified in the project's `platformio.ini`.
fixEnsure the required library is installed using PlatformIO's library manager (`pio lib install "Library Name"` or `lib_deps` in `platformio.ini`), or manually add the library's path using `build_flags = -I path/to/library` or `lib_extra_dirs` in `platformio.ini`.
Error: Unknown development platform 'platform_name'
PlatformIO cannot find or recognize the specified development platform (e.g., `espressif32`, `atmelavr`), usually due to a corrupted installation or the platform not being installed.
fixDelete the problematic platform folder from `~/.platformio/platforms/` (or `C:\Users\<username>\.platformio\platforms\` on Windows) and then reinstall it using `pio platform install platform_name` in the PlatformIO Core CLI. Restarting VS Code or PlatformIO Home might also help.
PermissionError: [WinError 5] Access is denied.
PlatformIO is being blocked from accessing or writing to certain files or directories, often by antivirus software, insufficient user permissions, or conflicting background processes.
fixTry running PlatformIO from a system terminal with administrator privileges (on Windows) or as a regular user (without `sudo` on Linux). Temporarily disable antivirus software or add the PlatformIO core directory (`~/.platformio` or `C:\Users\<username>\.platformio`) to its exclusion list. Deleting the `core_dir/packages` folder might also resolve the issue.
ModuleNotFoundError: No module named 'platformio'
The Python environment where PlatformIO is installed is corrupted, or the `platformio` package (or one of its dependencies like 'requests' or 'yaml') is missing or not accessible to the Python interpreter being used by PlatformIO.
fixCompletely uninstall PlatformIO (`pip uninstall platformio`), remove the entire `~/.platformio` folder, and then reinstall PlatformIO Core using the official installer script or ensure the Python environment associated with your IDE is correctly configured and has PlatformIO and its dependencies installed.
Upgrade
Version history
6.1.19latest on PyPI · released Feb 4, 2026
Audit
Dependencies
PythonrequiredPlatformIO Core is written in Python and requires Python 3.6 or newer to run.