installation.rst

Installation

Note

Please note that you do not need to install PlatformIO Core if you are going to use :ref:`ide_atom`. PlatformIO Core is built into PlatformIO IDE and you will be able to use it within PlatformIO IDE Terminal.

Also, PlatformIO IDE allows to install :ref:`core` Shell Commands (pio, platformio) globally to your system via Menu: PlatformIO > 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).

Contents

• System requirements
• Installation Methods
  • Python Package Manager
  • Installer Script
    • Super-Quick (Mac / Linux)
    • Local Download (Mac / Linux / Windows)
  • Mac OS X Homebrew
  • Full Guide
  • Development Version
• Troubleshooting

System requirements

Operating System:	Mac OS X, Linux (+ARM) or Windows
Python Interpreter:	Python 2.7 is required. PlatformIO does not support Python 3. Attention! Windows Users: Please Download the latest Python 2.7.x and install it. DON'T FORGET to select Add python.exe to Path feature on the "Customize" stage, otherwise Python Package Manager pip command will not be available.
Terminal Application:	All commands below should be executed in Command-line application (Terminal). For Mac OS X 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: Ubuntu/Debian users may need to add own "username" to the "dialout" group if they are not "root", doing this issuing a sudo usermod -a -G dialout yourusername. Install "udev" rules file 99-platformio-udev.rules (an instruction is located in the file). Raspberry Pi users, please read this article Enable serial port on Raspberry Pi.

Installation Methods

Please choose ONE of the following methods:

• Python Package Manager
• Installer Script
  • Super-Quick (Mac / Linux)
  • Local Download (Mac / Linux / Windows)
• Mac OS X Homebrew
• Full Guide
• Development Version

Python Package Manager

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

pip install -U platformio

If pip command is not available run easy_install pip or use :ref:`installation_installer_script` which will install pip and platformio automatically.

Note that you may run into permissions issues running these commands. You have a few options here:

• Run with sudo to install PlatformIO and dependencies globally
• Specify the pip install --user option to install local to your user
• Run the command in a virtualenv local to a specific project working set.

Installer Script

Super-Quick (Mac / Linux)

To install or upgrade PlatformIO paste that at a Terminal prompt (MAY require administrator access sudo):

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

Local Download (Mac / Linux / Windows)

To install or upgrade PlatformIO, download (save as...) get-platformio.py script. Then run the following (MAY require administrator access sudo):

# 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\get-platformio.py\script

# run it
C:\Python27\python.exe get-platformio.py

Mac OS X Homebrew

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

brew install platformio

Full Guide

1. Check a python version (only Python 2.7 is supported):

python --version

Windows Users only:

• Download Python 2.7 and install it.
• Add to PATH system variable ;C:\Python27;C:\Python27\Scripts; and reopen Command Prompt (cmd.exe) application. Please read this article How to set the path and environment variables in Windows.

2. Install a platformio and related packages:

pip install -U platformio

If your computer does not recognize pip command, try to install it first using these instructions.

For upgrading platformio to the latest version:

pip install -U platformio

Development Version

Warning

If you use :ref:`ide_atom`, please enable development version via Menu PlatformIO: Settings > PlatformIO IDE > Use development version of PlatformIO.

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 if you see the new commits in PlatformIO GitHub repository (branch: develop).

To revert to the latest stable version

pip uninstall platformio
pip install -U platformio

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 :ref:`faq`.