Freemallard's blog

Esp32 Development on Gentoo

2 minute read Published: 2026-08-01

Esp Development on Gentoo

Requirements

on Gentoo Linux

Installation

emerge -a dev-embedded/esp-idf dev-embedded/esptool dev-python/textual

You may however need to unmask the esp packages.

Troubleshooting install (2026-07-13)

Dating the writing of this blog post, something seems wrong with the installation process and you may encounter this error:

idf
Traceback (most recent call last):
  File "/usr/share/esp-idf/tools/idf.py", line 1205, in <module>
    main()
    ~~~~^^
  File "/usr/share/esp-idf/tools/idf.py", line 1027, in main
    cli = init_cli(verbose_output=checks_output)
  File "/usr/share/esp-idf/tools/idf.py", line 945, in init_cli
    all_actions = merge_action_lists(all_actions, extension.action_extensions(all_actions, project_dir))
                                                  ~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/site-packages/idf_component_manager/idf_extensions.py", line 385, in action_extensions
    if Version.coerce(os.getenv('ESP_IDF_VERSION')) >= Version.coerce('6.0.1'):
       ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/site-packages/idf_component_tools/semver/base.py", line 199, in coerce
    raise ValueError(f'Version string lacks a numerical component: {version_string!r}')
ValueError: Version string lacks a numerical component: ''

Clearly indicating a env variable is not set. As a temporary fix I simply exported the variable in my .zshrc to whatever version of idf I had installed.

echo 'export ESP_IDF_VERSION="6.0.2"' >> ~/.zshrc

There are also numerous env vars missing, such as $IDF_PATH or the whole .espressif folder. I suspect this is because I am did not install through eim ('espresif installation manager') but using the gentoo packages.

Add user to groups for serial port

If this is not already the case, when running idf, it might complain current user does not have sufficient permissions to access serial port (/dev/ttyUSB0 for instance). If so run:

doas usermod -a -G uucp <user>

or

doas usermod -a -G dialout <user>

Build your first project

After the troubleshooting process, the rest is pretty smooth sailing:

mkdir esp
cd ~/esp
cp -r /usr/share/esp-idf/examples/get-started/hello_world .
cd hello_world

Now build the project:

idf build

flash it:

idf flash

Finally, plug your esp32 and run the following command:

idf monitor

This should output the serial port detected and the chip type amongst other things, and at the end the prints of the program (see main.c source file):

Executing action: monitor
Serial port /dev/ttyUSB0:
Connecting..............
Detecting chip type... ESP32
...
Hello world!
This is esp32 chip with 2 CPU core(s), WiFi/BTBLE, silicon revision v3.1, 2MB external flash
Minimum free heap size: 304764 bytes
Restarting in 10 seconds...
Restarting in 9 seconds...
Restarting in 8 seconds...
Restarting in 7 seconds...
Restarting in 6 seconds...
Restarting in 5 seconds...
Restarting in 4 seconds...
Restarting in 3 seconds...
Restarting in 2 seconds...

exit by pressing Ctrl+]

Sources