{"id":4378,"library":"platformio","title":"PlatformIO","description":"PlatformIO is a powerful, open-source ecosystem for embedded software development, offering a collaborative environment that embraces declarative principles, test-driven methodologies, and modern toolchains. It features a cross-platform build system, unified package manager, and supports various development platforms and frameworks for microcontrollers and IoT devices. The current stable version is 6.1.19, with active and frequent minor updates.","status":"active","version":"6.1.19","language":"en","source_language":"en","source_url":"https://github.com/platformio/platformio-core","tags":["embedded","iot","cli","build-system","package-manager","firmware","microcontroller","development-tools","cross-platform"],"install":[{"cmd":"pip install platformio","lang":"bash","label":"Via Python Package Manager (recommended for CI/containers)"},{"cmd":"python3 -c \"$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py)\"","lang":"bash","label":"Via Installer Script (recommended for personal use)"}],"dependencies":[{"reason":"PlatformIO Core is written in Python and requires Python 3.6 or newer to run.","package":"Python"}],"imports":[],"quickstart":{"code":"import subprocess\nimport os\n\n# Create a dummy project directory\nproject_dir = \"my_pio_project\"\nos.makedirs(project_dir, exist_ok=True)\nos.chdir(project_dir)\n\ntry:\n    # Initialize a PlatformIO project for a common board (e.g., esp32dev)\n    # This will download necessary frameworks and tools into the project's .pio folder\n    print(f\"Initializing PlatformIO project in {os.getcwd()}...\")\n    result = subprocess.run(\n        [\"pio\", \"project\", \"init\", \"--board\", \"esp32dev\"],\n        capture_output=True, text=True, check=True\n    )\n    print(\"\\n--- pio project init Output ---\")\n    print(result.stdout)\n    if result.stderr:\n        print(\"\\n--- pio project init Errors ---\")\n        print(result.stderr)\n\n    # List installed packages within the project\n    print(\"\\nListing installed packages...\")\n    result = subprocess.run(\n        [\"pio\", \"pkg\", \"list\"],\n        capture_output=True, text=True, check=True\n    )\n    print(\"\\n--- pio pkg list Output ---\")\n    print(result.stdout)\n\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error executing PlatformIO command: {e}\")\n    print(f\"Stdout: {e.stdout}\")\n    print(f\"Stderr: {e.stderr}\")\nexcept FileNotFoundError:\n    print(\"Error: 'pio' command not found. Ensure PlatformIO Core CLI is installed and in your PATH.\")\nfinally:\n    # Clean up the created project directory\n    os.chdir(\"..\")\n    # In a real scenario, you might want to remove the directory:\n    # import shutil\n    # shutil.rmtree(project_dir)\n    print(f\"\\nQuickstart finished. Project directory: {project_dir}\")","lang":"python","description":"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."},"warnings":[{"fix":"Migrate 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.","message":"PlatformIO 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.","severity":"breaking","affected_versions":"6.0.0 and newer"},{"fix":"For 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.","message":"Having multiple PlatformIO Core installations or conflicting Python interpreters (especially on Windows) can lead to various issues, including `ImportError` or `pio` command not being recognized.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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.","message":"PlatformIO 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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Temporarily 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.","message":"Antivirus software can interfere with PlatformIO's background operations (e.g., downloading and unpacking packages), resulting in 'Access is denied' errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always 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.","message":"Not 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.","severity":"gotcha","affected_versions":"All versions, especially with Core 6.0's declarative approach emphasis"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}