# Installation

Note

Please note that you do not need to install PlatformIO Core (CLI) if you are going to use PlatformIO IDE. PlatformIO Core (CLI) is built into PlatformIO IDE and you will be able to use it within PlatformIO IDE Terminal.

If you need PlatformIO Core (CLI) outside PlatformIO IDE, please Install Shell Commands.

PlatformIO Core is written in Python and works on Windows, macOS, Linux, FreeBSD and ARM-based credit-card sized computers (Raspberry Pi, BeagleBone, CubieBoard, Samsung ARTIK, etc.).

- System requirements

- Installation Methods

  - Installer Script

    - Super-Quick (Mac / Linux)

    - Local Download (Mac / Linux / Windows)

  - Python Package Manager

  - macOS Homebrew

  - Virtual Environment

    - Prerequisites

    - Creating

- Development Version

- Install Shell Commands

  - Unix and Unix-like

    - Method 1

    - Method 2

  - Windows

- Uninstall PIO Core and dependent packages

- Integration with custom applications (extensions, plugins)

  - Prerequisite

    - Python Interpreter

    - Installer Script

  - Workflow

    - Step 1. Where is PlatformIO Core installed?

    - Step 2. Install PlatformIO Core

- Troubleshooting

## System requirements

Operating System

  Windows, macOS, Linux, FreeBSD, Linux ARMv6+

Python Interpreter

  Python 3.5+ (Python 2.7 is not recommended, support for it will be removed in the next releases). See detailed instruction on how to Install Python Interpreter for Windows.

Terminal Application

  All commands below should be executed in Command-line application (Terminal). For macOS and Linux OS - Terminal application, for Windows OS – `cmd.exe` application.

Access to Serial Ports (USB/UART)

  Windows Users: Please check that you have correctly installed USB driver from board manufacturer

  Linux Users:

  - Please install 99-platformio-udev.rules

  - Raspberry Pi users, please read this article Enable serial port on Raspberry Pi.

## Installation Methods

Please choose ONE of the following methods:

- Installer Script

  - Super-Quick (Mac / Linux)

  - Local Download (Mac / Linux / Windows)

- Python Package Manager

- macOS Homebrew

- Virtual Environment

  - Prerequisites

  - Creating

### Installer Script

Warning

PlatformIO DOES NOT require administrative/sudo permissions. Please install using default user account WITHOUT EXTRA PERMISSIONS.

#### Super-Quick (Mac / Linux)

To install or upgrade PlatformIO Core paste that at a Terminal prompt:

    python3 -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio/develop/scripts/get-platformio.py)"

    # or using `curl`

    curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py -o get-platformio.py
    python3 get-platformio.py

    # or using `wget`

    wget https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py -O get-platformio.py
    python3 get-platformio.py

#### Local Download (Mac / Linux / Windows)

To install or upgrade PlatformIO Core, download (save as…) get-platformio.py script. Then run the following:

    # change directory to folder where is located downloaded "get-platformio.py"
    cd /path/to/dir/where/is/located/get-platformio.py/script

    # run it
    python get-platformio.py

On Windows OS it may look like:

    # change directory to folder where is located downloaded "get-platformio.py"
    cd C:\path\to\dir\where\is\located\script\get-platformio.py

    # run it
    python.exe get-platformio.py

Note

If you need to have access to `platformio` or `platformio.exe` commands from other applications or terminal in your OS, please Install Shell Commands.

### Python Package Manager

Warning

We recommend using this method ONLY FOR Continuous Integration use cases or where your have full permissions to install PlatformIO Core into the global scope of your OS.

For personal using, and avoiding maintenance and upgrade issues, we HIGHLY RECOMMEND using Installer Script which installs PlatformIO Core into an isolated virtual environment and does not affect your OS.

The latest stable version of PlatformIO Core may be installed or upgraded via Python Package Manager (pip) as follows:

    pip install -U platformio

### macOS Homebrew

The latest stable version of PlatformIO may be installed or upgraded via macOS Homebrew Packages Manager (brew) as follows:

    brew install platformio

### Virtual Environment

PlatformIO Core may be installed into isolated Python environment. This method is very good if you don’t want to install PlatformIO Core Python’s dependencies (packages) into your global system scope. PlatformIO IDE uses this method to install PlatformIO Core.

Default and recommended environment folder is “core_dir/penv”. You can print environment folder path using the next command in your system terminal:

    python -c "import os; print(os.path.join(os.getenv('PLATFORMIO_CORE_DIR', os.path.join(os.path.expanduser('~'), '.platformio')), 'penv'))"

    ######################## Examples
    # Windows
    # C:\Users\UserName\.platformio\penv

    # Linux
    # ~/.platformio/penv
    # /home/username/.platformio/penv

    # macOS
    # ~/.platformio/penv
    # /Users/username/.platformio/penv

#### Prerequisites

1. Please remove existing PlatformIO Core environment folder if exists. See above command how to get path to environment folder.

2. Please check that you have a valid Python interpreter running a next command in system terminal. Python 2.7.9+ or Python 3.5+ is recommended.

       python --version

       # or, for Unix (Linux, Mac), you can use `python2` or `python3` aliases
       python2 --version
       python3 --version

   Warning

   Windows Users: If you already tried to install PlatformIO IDE and did not get success, please open system’s Control Panel > Installed Programs, and check if PlatformIO IDE tried to install an own isolated Python 2.7 version. Please uninstall it. Also is good to uninstall all Python interpreters from a system and install manually the latest Python using Install Python Interpreter guide.

3. Make sure `virtualenv --help` command exists in a system, otherwise, please install it manually using `pip install virtualenv` or `pip2 install virtualenv` command.

   If `pip` (Python Package Manager) does not exists, you have to install it manually. See https://pip.pypa.io/en/stable/installing/

#### Creating

1. Create a folder which contains all the necessary executables to use the packages that PIO Core would need using `virtualenv` command:

       virtualenv /path/to/.platformio/penv

       # If you want to use a custom Python interpreter
       virtualenv --python=/path/to/custom/python /path/to/.platformio/penv

       # EXAMPLES
       # Windows
       virtualenv C:\Users\UserName\.platformio\penv
       virtualenv --python=C:\Python27\python.exe  C:\Users\UserName\.platformio\penv

       # Unix (Linux, Mac)
       virtualenv ~/.platformio/penv
       virtualenv -p python3 ~/.platformio/penv

2. Activate virtual environment

       # Windows
       C:\Users\UserName\.platformio\penv\Scripts\activate

       # Unix (Linux, Mac)
       source /path/to/.platformio/penv/bin/activate
       # or
       . /path/to/.platformio/penv/bin/activate

3. Install PIO Core into virtual environment

       pip install -U platformio

If you plan to use PIO Core commands outside virtual environment, please Install Shell Commands.

## Development Version

Warning

If you use PlatformIO IDE, please enable development version:

- PlatformIO IDE for Atom: “Menu PlatformIO: Settings > PlatformIO IDE > Use development version of PlatformIO Core”

- VSCode: Set `platformio-ide.useDevelopmentPIOCore` to `true` in Settings.

Install the latest PlatformIO from the `develop` branch:

    # uninstall existing version
    pip uninstall platformio

    # install the latest development version of PlatformIO
    pip install -U https://github.com/platformio/platformio-core/archive/develop.zip

If you want to be up-to-date with the latest `develop` version of PlatformIO, then you need to re-install PlatformIO each time you see a new commits in PlatformIO GitHub repository (branch: develop) like so:

    pip install -U https://github.com/platformio/platformio-core/archive/develop.zip

Or:

    pio upgrade --dev

To revert to the latest stable version:

    pip uninstall platformio
    pip install -U platformio

## Install Shell Commands

PlatformIO Core (CLI) consists of 2 standalone tools in a system:

- `platformio` or `pio` (short alias) - CLI Guide

- `piodebuggdb` - alias of platformio debug

If you have PlatformIO IDE already installed, you do not need to install PlatformIO Core (CLI) separately. Just link these tools with your shell:

- Unix and Unix-like

  - Method 1

  - Method 2

- Windows

### Unix and Unix-like

In Unix and Unix-like systems, there are multiple ways to achieve this.

#### Method 1

You can export PlatformIO executables’ directory to the PATH environmental variable. This method will allow you to execute `platformio` commands from any terminal emulator as long as you’re logged in as the user PlatformIO is installed and configured for.

If you use Bash as your default shell, you can do it by editing either `~/.profile` or `~/.bash_profile` and adding the following line:

    export PATH=$PATH:~/.platformio/penv/bin

If you use Zsh, you can either edit `~/.zprofile` and add the code above, or for supporting both, Bash and Zsh, you can first edit `~/.profile` and add the code above, then edit `~/.zprofile` and add the following line:

    emulate sh -c '. ~/.profile'

After everything’s done, just restart your session (log out and log back in) and you’re good to go.

If you don’t know the difference between the two, check out this page.

#### Method 2

You can create system-wide symlinks. This method is not recommended if you have multiple users on your computer because the symlinks will be broken for other users and they will get errors while executing PlatformIO commands. If that’s not a problem, open your system terminal app and paste these commands (MAY require administrator access `sudo`):

    ln -s ~/.platformio/penv/bin/platformio /usr/local/bin/platformio
    ln -s ~/.platformio/penv/bin/pio /usr/local/bin/pio
    ln -s ~/.platformio/penv/bin/piodebuggdb /usr/local/bin/piodebuggdb

After that, you should be able to run PlatformIO from terminal. No restart is required.

### Windows

Please read one of these instructions How do I set or change the PATH system variable?

You need to edit system environment variable called `Path` and append `C:\Users\UserName\.platformio\penv\Scripts;` path in the beginning of a list (please replace `UserName` with your account name).

## Uninstall PIO Core and dependent packages

- Uninstall PIO Core tool

  >     # uninstall standalone PIO Core installed via `pip`
  >     pip uninstall platformio

  >     # uninstall Homebrew's PIO Core (only macOS users if you installed it via Homebrew before)
  >     brew uninstall platformio

- Dependent packages, global libraries are installed to core_dir folder (in user’s HOME directory). Just remove it.

## Integration with custom applications (extensions, plugins)

We recommend using PlatformIO Core Installer Script when you integrate PlatformIO Core into an application, such as extension or plugin for IDE. Examples that use this installer are:

- platformio-node-helpers, is used by PlatformIO IDE for VSCode and PlatformIO IDE for Atom

### Prerequisite

#### Python Interpreter

PlatformIO Core Installer Script is written in Python and is compatible with Python 2.7+ and Python 3.5+. We highly recommend using Python 3.

Python is installed by default on the most popular Unix OS (macOS, Linux, FreeBSD). If there is no Python on a user machine (you can check running `python --version`), we have 2 options:

1. Ask the user to install Python 3 using our guide Install Python Interpreter

2. You can automatically Download Portable Python 3 and unpack it in a cache folder of your application. Later, you can use `unpacked_protable_python_dir/python.exe` for the installer script.

#### Installer Script

There are 2 options on how to work with PlatformIO Core Installer Script:

1. Bundle get-platformio.py file into your application

2. Download get-platformio.py file on demand.

In both cases, you will need to have `get-platformio.py` script on the end-user machine. You can copy or download it to a cache/temporary folder.

A list of arguments and options for the installer script is available via

    python get-platformio.py --help

### Workflow

We will describe a simple workflow on how to automatically install PlatformIO Core (CLI) for end-user of your application/extension. We assume that `get-platformio.py` script is already copied/downloaded and exists on the end-user machine. See above how to get it.

#### Step 1. Where is PlatformIO Core installed?

You should check the PlatformIO Core installation state each time when the user starts your application. You need to call the Installer Script with `check core` arguments:

    python get-platformio.py check core

This command returns `0` “exit code” when PlatformIO Core is already installed and is ready for use, otherwise, the non-zero code of subprocess will be returned and you need to install PlatformIO Core (see Step #2 below).

If you need to have full information about PlatformIO Core installation state, please run with `--dump-state` option and specify a folder or a full path where to save data in JSON format:

    get-platformio.py check core --dump-state tmpdir/pioinstaller-state.json

Now, read JSON file and use `platformio_exe` binary to call PlatforIO Core using CLI (see CLI Guide). You can also export `penv_bin_dir` into system environment `PATH` variable and `platformio` command will be available without a full path.

Example of `pioinstaller-state.json` run on macOS:

    {
      "cache_dir": "/Users/Freedom/.platformio/.cache",
      "core_dir": "/Users/Freedom/.platformio",
      "core_version": "4.3.1",
      "installer_version": "0.2.0",
      "is_develop_core": false,
      "penv_bin_dir": "/Users/Freedom/.platformio/penv/bin",
      "penv_dir": "/Users/Freedom/.platformio/penv",
      "platformio_exe": "/Users/Freedom/.platformio/penv/bin/platformio",
      "python_exe": "/Users/Freedom/.platformio/penv/bin/python",
      "system": "darwin_x86_64"
    }

#### Step 2. Install PlatformIO Core

To install PlatformIO Core into the virtual environment in an automatic mode, please call installer script without any arguments:

    python get-platformio.py

Available options:

- `--verbose`, verbose output

- `--dev`, install the latest development version of PlatformIO Core

- `--ignore-python`, a path to Python to be ignored (multiple options and unix wildcards are allowed)

More options are available at `python get-platformio.py --help`.

Installer Script will return exit code `0` on success, otherwise non-zero code and error explanation.

Next time just use again `python get-platformio.py check core` as described in Step #1 (see above).

## Troubleshooting

Note

Linux OS: Don’t forget to install “udev” rules file 99-platformio-udev.rules (an instruction is located in the file).

Windows OS: Please check that you have correctly installed USB driver from board manufacturer

For further details, frequently questions, known issues, please refer to Frequently Asked Questions.

If you find any issues with PlatformIO Core Installer Script, please report to https://github.com/platformio/platformio-core-installer/issues