Install & Compatibility
Where this runs
tested against v2.3.1 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 36.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.4s · import 0.000s · 38MB
36MB installed
● package 36MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
IdfSize
✓ from esp_idf_size import IdfSize
✗ from esp_idf_size import IdfSize
The primary usage of `esp-idf-size` is through its command-line interface `idf_size`. You typically point it to the `.map` file generated during your ESP-IDF project build. For programmatic access, you can instantiate `IdfSize` (v2.0.0+) or `SizeReport` (v2.0.0+) to parse a map file and retrieve a size report object.
# Assuming you have an ESP-IDF project built, with a map file.
# The map file is typically found in build/<chip>/<project_name>.map
# e.g., build/esp32/hello-world.map
# Example using a placeholder map file path
import os
# Replace with the actual path to your .map file
# For demonstration, we'll use a dummy file path
map_file_path = os.environ.get('ESP_IDF_MAP_FILE', 'path/to/your/project/build/esp32/firmware.map')
if not os.path.exists(map_file_path):
print(f"Warning: Map file not found at '{map_file_path}'.")
print("Please replace 'path/to/your/project/build/esp32/firmware.map' ")
print("with the actual path to your ESP-IDF project's .map file.")
print("You can also set the ESP_IDF_MAP_FILE environment variable.")
else:
# Command line usage (most common)
print(f"\nRunning CLI tool on: {map_file_path}")
os.system(f"idf_size {map_file_path}")
# Programmatic usage (example for v2.0.0+)
try:
from esp_idf_size.core import IdfSize
# Create a dummy map file for programmatic example if not exists
if not os.path.exists(map_file_path):
with open(map_file_path, 'w') as f:
f.write(".text 0x40080000 0x100 app_start.o\n")
f.write(".rodata 0x3f400000 0x50 main.o\n")
f.write(".dram0.data 0x3f800000 0x20 data.o\n")
f.write(".flash.text 0x10000 0x80 bootloader.o\n")
f.write("0x42000000-0x42010000 iram_loader.text\n")
print("Created a dummy map file for programmatic example.")
idf_size_analyzer = IdfSize(map_file=map_file_path)
size_report = idf_size_analyzer.parse_and_get_size_report()
print("\nProgrammatic size report (excerpt):")
print(f"Total Flash Size: {size_report.total_flash_size_with_bootloader} bytes")
print(f"Total IRAM Size: {size_report.total_iram_size} bytes")
# print(size_report.to_json())
# Clean up dummy map file
if not os.environ.get('ESP_IDF_MAP_FILE') and os.path.exists(map_file_path):
os.remove(map_file_path)
print(f"Cleaned up dummy map file: {map_file_path}")
except ImportError:
print("\nCould not import esp_idf_size.core.IdfSize. Ensure esp-idf-size is installed.")
except Exception as e:
print(f"\nAn error occurred during programmatic analysis: {e}")
esp-idf-size --version
Upgrade
Version history
2.3.1latest on PyPI · released Aug 13, 2026
Audit
Dependencies
No dependency data recorded yet.