Install & Compatibility
Where this runs
tested against v3.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.366s · 45.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.9s · import 1.276s · 46MB
45MB installed
● package 45MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
build_apps
✓ from idf_build_apps import build_apps
find_apps
✓ from idf_build_apps import find_apps
flash_apps
✓ from idf_build_apps import flash_apps
This quickstart demonstrates how to use `idf-build-apps` to find and perform a dry run build for multiple ESP-IDF applications. It creates a temporary directory with two dummy ESP-IDF projects to ensure the example is runnable even without a pre-existing project structure. It highlights the crucial `IDF_PATH` environment variable and uses `dry_run=True` for safe execution. For a real build, set `dry_run=False` and ensure `IDF_PATH` points to your ESP-IDF installation.
import os
import shutil
from pathlib import Path
from idf_build_apps import build_apps, find_apps
# --- Create dummy ESP-IDF app structure for demonstration ---
# In a real scenario, 'my_app_1' and 'my_app_2' would be your actual ESP-IDF project directories.
# This setup allows the example to run without a complete ESP-IDF project, using dry_run.
dummy_root = Path('./idf_build_apps_quickstart_temp')
dummy_root.mkdir(exist_ok=True)
app1_path = dummy_root / 'my_app_1'
app1_path.mkdir(exist_ok=True)
(app1_path / 'CMakeLists.txt').write_text('cmake_minimum_required(VERSION 3.16)\ninclude($ENV{IDF_PATH}/tools/cmake/project.cmake)\nproject(my_app_1)')
(app1_path / 'sdkconfig').write_text('CONFIG_FREERTOS_HZ=100\n')
(app1_path / 'main.c').write_text('void app_main() {}')
app2_path = dummy_root / 'my_app_2'
app2_path.mkdir(exist_ok=True)
(app2_path / 'CMakeLists.txt').write_text('cmake_minimum_required(VERSION 3.16)\ninclude($ENV{IDF_PATH}/tools/cmake/project.cmake)\nproject(my_app_2)')
(app2_path / 'sdkconfig').write_text('CONFIG_FREERTOS_HZ=100\n')
(app2_path / 'main.c').write_text('void app_main() {}')
# --- Set up environment for idf-build-apps (critical) ---
# For actual building, IDF_PATH must point to a valid ESP-IDF installation.
# We use a placeholder here for dry_run to avoid immediate failure.
if 'IDF_PATH' not in os.environ:
print("WARNING: IDF_PATH environment variable is not set. Using a placeholder for dry_run.")
os.environ['IDF_PATH'] = '/path/to/esp-idf' # Replace with your actual ESP-IDF path
# --- Find applications ---
print(f"Searching for apps in: {dummy_root}")
apps = find_apps(
dummy_root, # The root directory to search for apps
recursive=True,
target='esp32', # Specify the target chip (e.g., esp32, esp32s3)
build_dir_name='build_idf_apps' # Name for the build output directory
)
print(f"Found {len(apps)} apps:")
for app in apps:
print(f" - {app.path.name} (target: {app.target}, build_dir: {app.build_path})")
# --- Build applications (dry run for safety and demonstrability) ---
# Set dry_run=False and ensure IDF_PATH is correct for a real build.
try:
build_apps(
apps,
parallel_jobs=1, # Number of parallel build jobs
dry_run=True, # Set to False for a real build
verbose=True,
# You can also pass 'work_dir', 'keep_partial_results', etc.
)
print("\nSuccessfully completed dry run for building apps.")
print("To perform an actual build, set 'dry_run=False' and ensure 'IDF_PATH' is correctly configured.")
except Exception as e:
print(f"\nAn error occurred during the build (dry_run): {e}")
print("This might be expected if IDF_PATH is not fully set up for a real ESP-IDF build.")
# --- Clean up dummy files ---
# shutil.rmtree(dummy_root)
# print(f"Cleaned up temporary directory: {dummy_root}")
idf-build-apps --version
Errors
Common errors & fixes
ValueError: 'IDF_PATH' environment variable is not set. Please set the path to ESP-IDF.
The Python environment or the shell from which idf-build-apps is executed does not have the IDF_PATH environment variable configured.
fixSet the `IDF_PATH` environment variable to the root directory of your ESP-IDF installation. For example, `export IDF_PATH=/path/to/esp-idf` in your shell, or configure it in your build script.
RuntimeError: No apps found under path: ...
The `find_apps` function could not locate any valid ESP-IDF projects (directories containing `CMakeLists.txt` and optionally `sdkconfig`) within the specified `search_paths` and `recursive` settings.
fixVerify that `search_paths` points to the correct directory containing your ESP-IDF apps, and that `recursive=True` is set if your apps are in subdirectories. Ensure `CMakeLists.txt` files are present in the app roots.
The target python version must be >= 3.10
You are attempting to run `idf-build-apps` version 3.0.0 or higher with a Python interpreter older than 3.10.
fixUpgrade your Python installation to version 3.10 or newer, or activate a virtual environment that uses Python 3.10+.
CMake Error at CMakeLists.txt:X (include): include could not find load file: /path/to/esp-idf/tools/cmake/project.cmake
The `IDF_PATH` environment variable is either incorrectly set, points to a non-existent directory, or the ESP-IDF installation is incomplete/corrupted, preventing CMake from finding core project files.
fixDouble-check that `IDF_PATH` points to the correct and complete ESP-IDF installation directory. If necessary, re-download or re-install ESP-IDF.
Upgrade
Version history
3.0.2latest on PyPI · released Apr 17, 2026
Audit
Dependencies
No dependency data recorded yet.