Standard Setup of Toolchain for Linux (Legacy GNU Make)¶

Note

Since ESP-IDF V4.0, the default build system is based on CMake. This documentation is for the legacy build system based on GNU Make. Support for this build system may be removed in future major releases.

Install Prerequisites¶

To compile with ESP-IDF you need to get the following packages:

CentOS 7:

sudo yum install gcc git wget make ncurses-devel flex bison gperf python python2-cryptography

Ubuntu and Debian:

sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools libffi-dev libssl-dev

Arch:

sudo pacman -S --needed gcc git make ncurses flex bison gperf python-pyserial python-cryptography python-future python-pyparsing python-pyelftools

Note

Some older Linux distributions may be missing some of the Python packages listed above (or may use pyserial version 2.x which is not supported by ESP-IDF). It is possible to install these packages via pip instead - as described in section Step 4. Install the Required Python Packages.

Toolchain Setup¶

ESP32 toolchain for Linux is available for download from Espressif website:

for 64-bit Linux:

https://dl.espressif.com/dl/xtensa-esp32-elf-gcc8_4_0-esp-2020r3-linux-amd64.tar.gz
for 32-bit Linux:

https://dl.espressif.com/dl/xtensa-esp32-elf-gcc8_4_0-esp-2020r3-linux-i686.tar.gz

Download this file, then extract it in ~/esp directory:

for 64-bit Linux:

mkdir -p ~/esp
cd ~/esp
tar -xzf ~/Downloads/xtensa-esp32-elf-gcc8_4_0-esp-2020r3-linux-amd64.tar.gz

for 32-bit Linux:

mkdir -p ~/esp
cd ~/esp
tar -xzf ~/Downloads/xtensa-esp32-elf-gcc8_4_0-esp-2020r3-linux-i686.tar.gz

The toolchain will be extracted into ~/esp/xtensa-esp32-elf/ directory.

To use it, you will need to update your PATH environment variable in ~/.profile file. To make xtensa-esp32-elf available for all terminal sessions, add the following line to your ~/.profile file:
```
export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"
```
Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ~/.profile file:
```
alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"'
```
Then when you need the toolchain you can type get_esp32 on the command line and the toolchain will be added to your PATH.

Note

If you have /bin/bash set as login shell, and both .bash_profile and .profile exist, then update .bash_profile instead. In CentOS, alias should set in .bashrc.
Log off and log in back to make the .profile changes effective. Run the following command to verify if PATH is correctly set:
```
printenv PATH
```
You are looking for similar result containing toolchain’s path at the beginning of displayed string:
```
$ printenv PATH
/home/user-name/esp/xtensa-esp32-elf/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
```
Instead of /home/user-name there should be a home path specific to your installation.

Permission issues /dev/ttyUSB0¶

With some Linux distributions you may get the Failed to open port /dev/ttyUSB0 error message when flashing the ESP32. This can be solved by adding the current user to the dialout group.

Arch Linux Users¶

To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6.

Backwards compatibility libraries are available in AUR for native and lib32 configurations:

Before installing these packages you might need to add the author’s public key to your keyring as described in the “Comments” section at the links above.

Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6.

Next Steps¶

To carry on with development environment setup, proceed to section Step 2. Get ESP-IDF.

Provide feedback about this document