{"id":4354,"library":"esp-idf-size","title":"ESP-IDF Firmware Size Analysis Tool","description":"esp-idf-size is a Python library and command-line tool for analyzing the firmware size of projects built with the Espressif ESP-IDF framework. It parses map files generated by the linker to provide detailed insights into memory usage by components, archives, files, and symbols. As of version 2.1.0, it's actively maintained with several releases per year.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/espressif/esp-idf-size","tags":["esp-idf","firmware","size-analysis","embedded","espressif"],"install":[{"cmd":"pip install esp-idf-size","lang":"bash","label":"Install esp-idf-size"}],"dependencies":[],"imports":[{"note":"Primary programmatic class for size analysis.","symbol":"IdfSize","correct":"from esp_idf_size.core import IdfSize"},{"note":"As of v2.0.0, the 'NG' implementation became default. Programmatic imports using the 'ng' submodule path are now incorrect. The `SizeReport` class is now directly under `esp_idf_size`.","wrong":"from esp_idf_size.ng.size_report import SizeReport","symbol":"SizeReport","correct":"from esp_idf_size.size_report import SizeReport"}],"quickstart":{"code":"# Assuming you have an ESP-IDF project built, with a map file.\n# The map file is typically found in build/<chip>/<project_name>.map\n# e.g., build/esp32/hello-world.map\n\n# Example using a placeholder map file path\nimport os\n\n# Replace with the actual path to your .map file\n# For demonstration, we'll use a dummy file path\nmap_file_path = os.environ.get('ESP_IDF_MAP_FILE', 'path/to/your/project/build/esp32/firmware.map')\n\nif not os.path.exists(map_file_path):\n    print(f\"Warning: Map file not found at '{map_file_path}'.\")\n    print(\"Please replace 'path/to/your/project/build/esp32/firmware.map' \")\n    print(\"with the actual path to your ESP-IDF project's .map file.\")\n    print(\"You can also set the ESP_IDF_MAP_FILE environment variable.\")\nelse:\n    # Command line usage (most common)\n    print(f\"\\nRunning CLI tool on: {map_file_path}\")\n    os.system(f\"idf_size {map_file_path}\")\n\n    # Programmatic usage (example for v2.0.0+)\n    try:\n        from esp_idf_size.core import IdfSize\n        # Create a dummy map file for programmatic example if not exists\n        if not os.path.exists(map_file_path):\n            with open(map_file_path, 'w') as f:\n                f.write(\".text          0x40080000        0x100 app_start.o\\n\")\n                f.write(\".rodata        0x3f400000         0x50 main.o\\n\")\n                f.write(\".dram0.data    0x3f800000         0x20 data.o\\n\")\n                f.write(\".flash.text    0x10000            0x80 bootloader.o\\n\")\n                f.write(\"0x42000000-0x42010000       iram_loader.text\\n\")\n            print(\"Created a dummy map file for programmatic example.\")\n\n        idf_size_analyzer = IdfSize(map_file=map_file_path)\n        size_report = idf_size_analyzer.parse_and_get_size_report()\n        print(\"\\nProgrammatic size report (excerpt):\")\n        print(f\"Total Flash Size: {size_report.total_flash_size_with_bootloader} bytes\")\n        print(f\"Total IRAM Size: {size_report.total_iram_size} bytes\")\n        # print(size_report.to_json())\n\n        # Clean up dummy map file\n        if not os.environ.get('ESP_IDF_MAP_FILE') and os.path.exists(map_file_path):\n            os.remove(map_file_path)\n            print(f\"Cleaned up dummy map file: {map_file_path}\")\n\n    except ImportError:\n        print(\"\\nCould not import esp_idf_size.core.IdfSize. Ensure esp-idf-size is installed.\")\n    except Exception as e:\n        print(f\"\\nAn error occurred during programmatic analysis: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Remove `--ng` flag and `ESP_IDF_SIZE_NG` environment variable. Do not attempt to use `--legacy` mode. The tool will automatically use the updated 'NG' logic.","message":"Starting with v2.0.0, the 'NG' (Next Generation) implementation became the default behavior. The `--ng` command-line flag and `ESP_IDF_SIZE_NG` environment variable are no longer supported and should be removed. The `--legacy` mode has also been removed.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update your import statements. For example, change `from esp_idf_size.ng.size_report import SizeReport` to `from esp_idf_size.size_report import SizeReport`.","message":"For programmatic users, import paths for the core functionality changed in v2.0.0 due to the 'NG' implementation becoming default. Objects previously imported from `esp_idf_size.ng` (e.g., `esp_idf_size.ng.size_report.SizeReport`) now reside directly under `esp_idf_size` (e.g., `esp_idf_size.size_report.SizeReport`).","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your build environment generates map files with UTF-8 encoding. If parsing manually, explicitly specify `encoding='utf-8'` when opening map files.","message":"Map files must be opened using UTF-8 encoding. Issues with non-UTF-8 characters in map files (e.g., in symbol names or paths) can lead to parsing errors or incorrect reports.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}