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.
- System requirements
- Installation Methods
- Development Version
- Install Shell Commands
- Uninstall PIO Core and dependent packages
Windows, macOS, Linux, FreeBSD, Linux ARMv6+
Python 2.7 is required. PlatformIO does not support Python 3. See detailed instruction how to Install Python Interpreter for Windows.
All commands below should be executed in
application (Terminal). For macOS and Linux OS - Terminal application,
for Windows OS –
|Access to Serial Ports (USB/UART):|
Windows Users: Please check that you have correctly installed USB driver from board manufacturer
Please choose ONE of the following methods:
The latest stable version of PlatformIO may be installed or upgraded via Python Package Manager (pip) as follows:
pip install -U platformio
pip command is not available run
easy_install pip or use
Installer Script which will install
Note that you may run into permissions issues running these commands. You have a few options here:
To install or upgrade PlatformIO paste that at a Terminal prompt
(MAY require administrator access
python -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio/develop/scripts/get-platformio.py)"
To install or upgrade PlatformIO, download (save as…)
script. Then run the following (MAY require administrator access
# 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
The latest stable version of PlatformIO may be installed or upgraded via macOS Homebrew Packages Manager (brew) as follows:
brew install platformio
- Check a
pythonversion (only Python 2.7 is supported):
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.
- Install a
platformioand related packages:
pip install -U platformio
If your computer does not recognize
pip command, try to install it first
using these instructions.
platformio to the latest version:
pip install -U platformio
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 “home_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_HOME_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
Please remove existing PlatformIO Core environment folder if exists. See above how to get a path.
Please check that you have a valid Python interpreter running a next command in system terminal. Python 2.7.9+ is recommended.
python --version # or, for Unix (Linux, Mac), you can use `python2` or `python2.7` aliases python2 --version python2.7 --version
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 2.7 using Install Python Interpreter guide.
Please note, that you can have Python 3 installed in a system too. You will need to specify full path to Python 2.7 when creating a virtual environment (explained below).
virtualenv --helpcommand exists in a system, otherwise, please install it manually using
pip install virtualenvor
pip2 install virtualenvcommand.
pip(Python Package Manager) does not exists, you have to install it manually. See https://pip.pypa.io/en/stable/installing/
Create a folder which contains all the necessary executables to use the packages that PIO Core would need using
virtualenv /path/to/.platformio/penv # if you have multiple Python interpreters in a system, please specify # a valid Python 2.7 via ``-p, --python`` option: virtualenv -p python2 /path/to/.platformio/penv # or using full path to Python 2.7 interpreter virtualenv --python=/path/to/python2.7 /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 python2.7 ~/.platformio/penv
Activate virtual environment
# Windows C:\Users\UserName\.platformio\penv # Unix (Linux, Mac) source /path/to/.platformio/penv/bin/activate # or . /path/to/.platformio/penv/bin/activate
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.
If you use PlatformIO IDE, please enable development version:
- Atom: “Menu PlatformIO: Settings > PlatformIO IDE > Use development version of PlatformIO Core”
- VSCode: Set
Install the latest PlatformIO from the
# 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
PlatformIO Core (CLI) consists of 2 standalone tools in a system:
In Unix and Unix-like systems, there are multiple ways to achieve this.
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
~/.bash_profile and adding the following line:
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.
Go to the PlatformIO menu → Settings → PlatformIO IDE, scroll down to the Custom PATH for `platformio` command and enter the following:
~/.platformio/penv/bin. After you’ve done that, you’ll need to go to the PlatformIO menu → Settings → PlatformIO IDE Terminal, scroll down to the Toggles section and uncheck the Login Shell checkbox. Finally, restart your editor/IDE and check out the result.
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
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.
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 home_dir folder (in user’s HOME directory). Just remove it.
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.