Installation¶

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

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.

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.

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

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).