Guides › Setup · Linux and macOS

ESP-IDF: "python_env … does not exist" after export.sh

You run . ./export.sh in the ESP-IDF folder and it stops, saying the Python virtual environment it expects under ~/.espressif/python_env does not exist. The fix is almost always one command you have not run yet.

ESP-IDF 5.x and 6.x · Linux and macOS · updated 27 October 2026

install.sh and export.sh do different things

• install.sh creates things: it downloads the toolchains into ~/.espressif/tools and creates a Python virtual environment for this ESP-IDF version in ~/.espressif/python_env/. You run it once per ESP-IDF version (and again after updating it).
• export.sh only activates what install.sh created, in the current terminal. If the environment was never created, there is nothing to activate.

Fix 1: run install.sh first

In the ESP-IDF folder, install the tools for the chips you use, then export:

cd ~/esp/esp-idf
./install.sh esp32          # or: ./install.sh esp32,esp32s3,esp32c3   or: ./install.sh all
. ./export.sh

Note the dot and space in . ./export.sh: the script must run in the current shell, not in a child process, or the changes disappear when it ends.

Fix 2: install.sh fails to create the environment

install.sh needs a system Python 3 with the venv module. On Debian and Ubuntu it is a separate package:

sudo apt install python3 python3-venv python3-pip git wget flex bison gperf cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

On macOS, install Python 3 (for example with Homebrew: brew install python cmake ninja dfu-util), then check that python3 --version works in a new terminal. Run ./install.sh again afterwards.

Fix 3: you switched or updated ESP-IDF

Each ESP-IDF version has its own environment, named after the ESP-IDF and Python versions (for example idf6.1_py3.12_env). After git checkout of another release, a git pull, or an update of your system Python, run ./install.sh again in that ESP-IDF folder.

Fix 4: a broken environment

If an interrupted installation left a half-created environment, delete just that folder and run ./install.sh again:

ls ~/.espressif/python_env/
rm -rf ~/.espressif/python_env/idf6.1_py3.12_env   # the one for your version
./install.sh esp32

Check that it worked

. ./export.sh
idf.py --version