********
IDF Size
********

IDF Size is a tool for analyzing statically-allocated memory in ESP-IDF project. The main functionality is provided by the esp-idf-size_ Python package, while :ref:`idf.py` offers a more user-friendly and higher-level interface through the ``size``, ``size-components``, and ``size-files`` sub-commands. These sub-commands allow you to specify various options, such as the report's output format. For more details, please use the ``--help`` option. ESP-IDF also includes a handy ``idf_size.py`` wrapper to invoke the esp-idf-size_ Python module. For more information, use the command ``idf_size.py --help``.

Size Summary ``idf.py size``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This output provides a summary of the statically-allocated memory for different memory types in the firmware binary:

.. code-block:: bash

    $ idf.py size
                                 Memory Type Usage Summary
    ┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
    ┃ Memory Type/Section   ┃ Used [bytes] ┃ Used [%] ┃ Remain [bytes] ┃ Total [bytes] ┃
    ┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
    │ Flash Code            │        80666 │     2.41 │        3261638 │       3342304 │
    │    .text              │        80666 │     2.41 │                │               │
    │ IRAM                  │        51835 │    39.55 │          79237 │        131072 │
    │    .text              │        50807 │    38.76 │                │               │
    │    .vectors           │         1027 │     0.78 │                │               │
    │ Flash Data            │        38224 │     0.91 │        4156048 │       4194272 │
    │    .rodata            │        37968 │     0.91 │                │               │
    │    .appdesc           │          256 │     0.01 │                │               │
    │ DRAM                  │        11236 │     6.22 │         169500 │        180736 │
    │    .data              │         8988 │     4.97 │                │               │
    │    .bss               │         2248 │     1.24 │                │               │
    │ RTC SLOW              │           24 │     0.29 │           8168 │          8192 │
    │    .rtc_slow_reserved │           24 │     0.29 │                │               │
    └───────────────────────┴──────────────┴──────────┴────────────────┴───────────────┘
    Total image size: 179712 bytes (.bin may be padded larger)

Espressif chips include various :doc:`/api-guides/memory-types`, which are detailed in the `Technical Reference Manual (TRM) <{IDF_TARGET_TRM_EN_URL}>`__. These memory types are listed in the ``Memory Type`` column, along with the ELF ``Sections`` that are loaded into each type. The ``Used`` columns display the memory usage for each specific memory type or section. The ``Remain`` column indicates the remaining available memory for the specified memory type. The ``Total`` column shows the total available memory for that memory type, based on the memory region sizes defined in the linker script that map into the memory type.

.. note::

    The ``Total`` memory available for each memory type, like ``IRAM``, is determined by the memory region sizes specified in the link map file, which is generated by the linker script, with the MEMORY command, during the build process. The esp-idf-size tool includes YAML files for each target, detailing memory type ranges based on the TRM. The memory ranges from the link map file are mapped to these memory type ranges. This process calculates the total memory available for different memory types. Note that the total available size may differ from what is stated in the TRM, as some memory portions may be reserved for purposes such as the bootloader or cache, depending on the configuration. The remaining memory is calculated by subtracting the sizes of output ``Sections`` loaded to the specific memory type from the ``Total`` size.

.. note::

    Certain memory types might map to the same hardware memory. On some targets, ``IRAM`` and ``DRAM`` could be mapped to the same hardware memory but at different virtual addresses, accessible through data and instruction buses. These memory types are referred to as ``DIRAM`` in the ``Memory Type`` column.

Below is a description of the most interesting memory types and output sections. Please note that all output sections with a non-zero size are included in the summary. Their names are determined by the output section names specified in the linker script.

- ``DRAM``: Total amount of DRAM allocated at compile time. ``Remain`` indicates the amount of DRAM left to be used as heap memory at runtime. Note that due to meta data overhead, implementation constraints, and startup heap allocations, the actual size of the DRAM heap is smaller.

    - ``.data``: Amount of DRAM allocated at compile time for the ``.data`` (i.e., all statically allocated variables that are initialized to non-zero values). ``.data`` also consumes space in the binary image to store the non-zero initialization values.

    - ``.bss``: Amount of DRAM allocated at compile time for ``.bss``  (i.e., all statically allocated variables that are initialized to zero). ``.bss`` does not consume extra space in flash.

- ``IRAM``: Total amount of IRAM allocated at compile time. ``Remain`` indicates the amount of IRAM left to be used as heap memory at runtime. Note that due to meta data overhead, implementation constraints, and startup heap allocations, the actual size of the IRAM heap is smaller.

    - ``.text``: Amount of IRAM used for ``.text`` (i.e., all code that is executed from :ref:`IRAM <iram>`). ``.text`` also consumes space in the binary image as the code is initially stored there and is then copied over to IRAM on startup.

- ``Flash Code``: Code executed from flash.

    - ``.text``: Amount of flash used for ``.text`` (i.e., all code that is executed via the flash cache, see :ref:`IROM <irom>`).
- ``Flash Data``: Data stored in flash.

    - ``.rodata``: Amount of flash used for ``.rodata`` (i.e., read-only data that is loaded via the flash cache, see :ref:`DROM <drom>`).

- ``Total image size`` is the estimated total size of the binary file.

Component Usage Summary ``idf.py size-components``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The summary output from ``idf.py size`` lacks sufficient detail to identify the primary cause of excessive binary size. For a more detailed analysis, use ``idf.py size-components``, which indicates the contribution of each static library archive to the final binary size.

.. code-block:: bash

    $ idf.py size-components
                                                                     Per-archive contributions to ELF file
    ┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━┳━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
    ┃ Archive File            ┃ Total Size ┃ DRAM ┃ .bss ┃ .data ┃  IRAM ┃ .text ┃ .vectors ┃ Flash Code ┃ .text ┃ Flash Data ┃ .rodata ┃ .appdesc ┃ RTC SLOW ┃ .rtc_slow_reserved ┃
    ┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━╇━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
    │ libnet80211.a           │     116712 │ 9454 │ 8393 │  1061 │  5310 │  5310 │        0 │      89698 │ 89698 │      12250 │   12250 │        0 │        0 │                  0 │
    │ libmbedcrypto.a         │     105863 │  141 │   81 │    60 │     0 │     0 │        0 │      71251 │ 71251 │      34471 │   34471 │        0 │        0 │                  0 │
    │ liblwip.a               │      85394 │ 2470 │ 2458 │    12 │     0 │     0 │        0 │      79486 │ 79486 │       3438 │    3438 │        0 │        0 │                  0 │
    │ libpp.a                 │      66484 │ 3915 │ 1444 │  2471 │ 20004 │ 20004 │        0 │      37714 │ 37714 │       4851 │    4851 │        0 │        0 │                  0 │
    │ libc.a                  │      59525 │  576 │  316 │   260 │     0 │     0 │        0 │      55513 │ 55513 │       3436 │    3436 │        0 │        0 │                  0 │
    │ libesp_app_format.a     │      53209 │   10 │   10 │     0 │     0 │     0 │        0 │        417 │   417 │      52782 │   52526 │      256 │        0 │                  0 │
    │ libwpa_supplicant.a     │      45251 │ 1241 │ 1233 │     8 │     0 │     0 │        0 │      42315 │ 42315 │       1695 │    1695 │        0 │        0 │                  0 │
    │ libphy.a                │      44360 │ 1229 │  637 │   592 │  8922 │  8922 │        0 │      34209 │ 34209 │          0 │       0 │        0 │        0 │                  0 │
    │ libfreertos.a           │      21108 │ 3841 │  741 │  3100 │ 15594 │ 15594 │        0 │        467 │   467 │       1206 │    1206 │        0 │        0 │                  0 │
    │ libesp_hw_support.a     │      15147 │  256 │   96 │   160 │  5654 │  5654 │        0 │       8264 │  8264 │        949 │     949 │        0 │       24 │                 24 │
    │ libnvs_flash.a          │      14522 │   24 │   24 │     0 │     0 │     0 │        0 │      14250 │ 14250 │        248 │     248 │        0 │        0 │                  0 │
    │ libesp_system.a         │      13304 │  793 │  313 │   480 │  4267 │  4267 │        0 │       7575 │  7575 │        669 │     669 │        0 │        0 │                  0 │
    │ libhal.a                │      13078 │ 4000 │    8 │  3992 │  5810 │  5810 │        0 │       3143 │  3143 │        125 │     125 │        0 │        0 │                  0 │
    │ libheap.a               │      12009 │   12 │    8 │     4 │  7298 │  7298 │        0 │       3109 │  3109 │       1590 │    1590 │        0 │        0 │                  0 │
    │ libspi_flash.a          │      11613 │ 1348 │   24 │  1324 │  8932 │  8932 │        0 │        865 │   865 │        468 │     468 │        0 │        0 │                  0 │
    │ libesp_driver_uart.a    │       7255 │  228 │   32 │   196 │     0 │     0 │        0 │       6434 │  6434 │        593 │     593 │        0 │        0 │                  0 │
    │ libesp_netif.a          │       5954 │   33 │   29 │     4 │     0 │     0 │        0 │       5758 │  5758 │        163 │     163 │        0 │        0 │                  0 │
    │ libvfs.a                │       4180 │  236 │   44 │   192 │     0 │     0 │        0 │       3757 │  3757 │        187 │     187 │        0 │        0 │                  0 │
    │ libesp_mm.a             │       4003 │  160 │  124 │    36 │  1002 │  1002 │        0 │       2627 │  2627 │        214 │     214 │        0 │        0 │                  0 │
    │ libesp_wifi.a           │       3919 │  527 │   47 │   480 │   357 │   357 │        0 │       2993 │  2993 │         42 │      42 │        0 │        0 │                  0 │
    │ libesp_timer.a          │       3471 │   56 │   24 │    32 │  1621 │  1621 │        0 │       1659 │  1659 │        135 │     135 │        0 │        0 │                  0 │
    │ libxtensa.a             │       3412 │ 1044 │    0 │  1044 │  2213 │  1789 │      424 │        119 │   119 │         36 │      36 │        0 │        0 │                  0 │
    │ libnewlib.a             │       3352 │  360 │  200 │   160 │  1535 │  1535 │        0 │       1346 │  1346 │        111 │     111 │        0 │        0 │                  0 │
    │ libesp_event.a          │       3137 │    4 │    4 │     0 │     0 │     0 │        0 │       2992 │  2992 │        141 │     141 │        0 │        0 │                  0 │
    │ libesp_phy.a            │       2400 │   53 │   36 │    17 │   235 │   235 │        0 │       1868 │  1868 │        244 │     244 │        0 │        0 │                  0 │
    │ libbootloader_support.a │       1939 │    0 │    0 │     0 │  1805 │  1805 │        0 │         94 │    94 │         40 │      40 │        0 │        0 │                  0 │
    │ libesp_partition.a      │       1865 │    8 │    8 │     0 │     0 │     0 │        0 │       1689 │  1689 │        168 │     168 │        0 │        0 │                  0 │
    │ libesp_common.a         │       1793 │    0 │    0 │     0 │     0 │     0 │        0 │         51 │    51 │       1742 │    1742 │        0 │        0 │                  0 │
    │ liblog.a                │       1706 │  280 │  272 │     8 │   276 │   276 │        0 │       1102 │  1102 │         48 │      48 │        0 │        0 │                  0 │
    │ libefuse.a              │       1672 │   64 │    4 │    60 │     0 │     0 │        0 │       1427 │  1427 │        181 │     181 │        0 │        0 │                  0 │
    │ libsoc.a                │       1540 │    0 │    0 │     0 │    37 │    37 │        0 │         39 │    39 │       1464 │    1464 │        0 │        0 │                  0 │
    │ libstdc++.a             │       1502 │   21 │   17 │     4 │     0 │     0 │        0 │       1282 │  1282 │        199 │     199 │        0 │        0 │                  0 │
    │ libesp_ringbuf.a        │       1121 │    0 │    0 │     0 │  1024 │  1024 │        0 │          0 │     0 │         97 │      97 │        0 │        0 │                  0 │
    │ libmain.a               │       1027 │    8 │    8 │     0 │     0 │     0 │        0 │        964 │   964 │         55 │      55 │        0 │        0 │                  0 │
    │ libpthread.a            │        678 │   20 │   12 │     8 │     0 │     0 │        0 │        604 │   604 │         54 │      54 │        0 │        0 │                  0 │
    │ libesp_vfs_console.a    │        599 │   12 │   12 │     0 │     0 │     0 │        0 │        415 │   415 │        172 │     172 │        0 │        0 │                  0 │
    │ libxt_hal.a             │        475 │    0 │    0 │     0 │   443 │   443 │        0 │          0 │     0 │         32 │      32 │        0 │        0 │                  0 │
    │ librtc.a                │        456 │    0 │    0 │     0 │   456 │   456 │        0 │          0 │     0 │          0 │       0 │        0 │        0 │                  0 │
    │ libcore.a               │        331 │   33 │   33 │     0 │     0 │     0 │        0 │        255 │   255 │         43 │      43 │        0 │        0 │                  0 │
    │ libesp_coex.a           │        277 │    0 │    0 │     0 │   118 │   118 │        0 │        159 │   159 │          0 │       0 │        0 │        0 │                  0 │
    │ libapp_update.a         │        186 │    4 │    4 │     0 │     0 │     0 │        0 │        152 │   152 │         30 │      30 │        0 │        0 │                  0 │
    │ libesp_rom.a            │        102 │    0 │    0 │     0 │   102 │   102 │        0 │          0 │     0 │          0 │       0 │        0 │        0 │                  0 │
    │ libgcc.a                │         89 │    0 │    0 │     0 │     0 │     0 │        0 │         89 │    89 │          0 │       0 │        0 │        0 │                  0 │
    │ libcxx.a                │         52 │    0 │    0 │     0 │     0 │     0 │        0 │         52 │    52 │          0 │       0 │        0 │        0 │                  0 │
    │ libnvs_sec_provider.a   │          5 │    0 │    0 │     0 │     0 │     0 │        0 │          5 │     5 │          0 │       0 │        0 │        0 │                  0 │
    │ (exe)                   │          3 │    0 │    0 │     0 │     3 │     0 │        3 │          0 │     0 │          0 │       0 │        0 │        0 │                  0 │
    └─────────────────────────┴────────────┴──────┴──────┴───────┴───────┴───────┴──────────┴────────────┴───────┴────────────┴─────────┴──────────┴──────────┴────────────────────┘


Generally, one static library archive is built per component, although some are binary libraries included by a particular component, for example, ``libnet80211.a`` is included by ``esp_wifi`` component. There are also toolchain libraries such as ``libc.a`` and ``libgcc.a`` listed here, these provide Standard C/C++ Library and toolchain built-in functionality.

If the project is simple and only has a ``main`` component, then all of the project's code will be shown under ``libmain.a``. If the project includes its own components (see :doc:`/api-guides/build-system`), then they will each be shown on a separate line.

The table is sorted in descending order of the total contribution of the static archive to the binary size. The columns indicate memory types and output sections as detailed in the Size Summary.

.. note::

    The ``(exe)`` archive is a special archive that contains object files directly linked into the final binary, meaning they are not part of any archive file.

.. note::

    The size of the ``.rodata`` section in the ``Flash Data`` memory type may appear very large for a single archive. This occurs due to linker relaxations. The linker may attempt to combine object file sections with ``MERGE`` and ``STRINGS`` flags from all archives into one to perform tail string optimization. Consequently, one archive may end up with a very large ``.rodata`` section, containing string literals from other archives. This is evident in the ``.rodata`` section of the ``libesp_app_format.a`` archive. The specific compiler behavior here can be turned off by enabling :ref:`CONFIG_COMPILER_NO_MERGE_CONSTANTS` option (only for GCC toolchain), please read help for more details.


Source File Usage Summary ``idf.py size-files``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For even more details, run ``idf.py size-files`` to get a summary of the contribution each object file has made to the final binary size. Each object file corresponds to a single source file.

.. code-block:: bash

    $ idf.py size-files
                                                                                Per-file contributions to ELF file
    ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━┳━━━━━━┳━━━━━━━┳━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
    ┃ Object File                         ┃ Total Size ┃ DRAM ┃ .bss ┃ .data ┃ IRAM ┃ .text ┃ .vectors ┃ Flash Code ┃ .text ┃ Flash Data ┃ .rodata ┃ .appdesc ┃ RTC SLOW ┃ .rtc_slow_reserved ┃
    ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━╇━━━━━━╇━━━━━━━╇━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
    │ esp_app_desc.c.obj                  │      72313 │   10 │   10 │     0 │    0 │     0 │        0 │        417 │   417 │      71886 │   71630 │      256 │        0 │                  0 │
    │ x509_crt_bundle.S.obj               │      67810 │    0 │    0 │     0 │    0 │     0 │        0 │          0 │     0 │      67810 │   67810 │        0 │        0 │                  0 │
    │ ecp_curves.c.obj                    │      36415 │    0 │    0 │     0 │    0 │     0 │        0 │       6875 │  6875 │      29540 │   29540 │        0 │        0 │                  0 │
    │ phy_chip_v7.o                       │      19384 │  783 │  533 │   250 │ 2186 │  2186 │        0 │      16415 │ 16415 │          0 │       0 │        0 │        0 │                  0 │
    │ wl_cnx.o                            │      18567 │ 3891 │ 3889 │     2 │  277 │   277 │        0 │      13343 │ 13343 │       1056 │    1056 │        0 │        0 │                  0 │
    │ ieee80211_output.o                  │      15498 │   27 │   25 │     2 │ 2083 │  2083 │        0 │      12840 │ 12840 │        548 │     548 │        0 │        0 │                  0 │
    │ pp.o                                │      14722 │ 1207 │   53 │  1154 │ 7286 │  7286 │        0 │       5590 │  5590 │        639 │     639 │        0 │        0 │                  0 │
    │ libc_a-vfprintf.o                   │      14084 │    0 │    0 │     0 │    0 │     0 │        0 │      13508 │ 13508 │        576 │     576 │        0 │        0 │                  0 │
    │ phy_chip_v7_cal.o                   │      13997 │  229 │   54 │   175 │ 4039 │  4039 │        0 │       9729 │  9729 │          0 │       0 │        0 │        0 │                  0 │
    │ pm.o                                │      13958 │  532 │  488 │    44 │ 3630 │  3630 │        0 │       8823 │  8823 │        973 │     973 │        0 │        0 │                  0 │
    │ libc_a-svfprintf.o                  │      13753 │    0 │    0 │     0 │    0 │     0 │        0 │      13177 │ 13177 │        576 │     576 │        0 │        0 │                  0 │
    │ ieee80211_sta.o                     │      13711 │   50 │   38 │    12 │ 1443 │  1443 │        0 │      11181 │ 11181 │       1037 │    1037 │        0 │        0 │                  0 │
    │ ieee80211_ioctl.o                   │      13479 │  120 │  116 │     4 │  271 │   271 │        0 │      11127 │ 11127 │       1961 │    1961 │        0 │        0 │                  0 │
    │ ieee80211_scan.o                    │      12037 │  327 │  309 │    18 │    0 │     0 │        0 │      11119 │ 11119 │        591 │     591 │        0 │        0 │                  0 │
    │ ieee80211_hostap.o                  │      11970 │   42 │   41 │     1 │    0 │     0 │        0 │      10898 │ 10898 │       1030 │    1030 │        0 │        0 │                  0 │
    │ nd6.c.obj                           │      11815 │  940 │  932 │     8 │    0 │     0 │        0 │      10764 │ 10764 │        111 │     111 │        0 │        0 │                  0 │
    │ phy_chip_v7_ana.o                   │      11039 │  217 │   50 │   167 │ 2697 │  2697 │        0 │       8125 │  8125 │          0 │       0 │        0 │        0 │                  0 │
    │ ieee80211_ht.o                      │      11033 │    5 │    4 │     1 │ 1179 │  1179 │        0 │       8466 │  8466 │       1383 │    1383 │        0 │        0 │                  0 │
    │ sae.c.obj                           │      11003 │    0 │    0 │     0 │    0 │     0 │        0 │      10971 │ 10971 │         32 │      32 │        0 │        0 │                  0 │
    │ tasks.c.obj                         │      10753 │  712 │  696 │    16 │ 9416 │  9416 │        0 │          0 │     0 │        625 │     625 │        0 │        0 │                  0 │
    │ libc_a-svfiprintf.o                 │      10446 │    0 │    0 │     0 │    0 │     0 │        0 │       9398 │  9398 │       1048 │    1048 │        0 │        0 │                  0 │
    │ libc_a-vfiprintf.o                  │      10092 │    0 │    0 │     0 │    0 │     0 │        0 │       9516 │  9516 │        576 │     576 │        0 │        0 │                  0 │
    │ wpa.c.obj                           │       9688 │  872 │  872 │     0 │    0 │     0 │        0 │       8816 │  8816 │          0 │       0 │        0 │        0 │                  0 │
    │ tcp_in.c.obj                        │       8904 │   52 │   52 │     0 │    0 │     0 │        0 │       8698 │  8698 │        154 │     154 │        0 │        0 │                  0 │
    [... additional lines removed ...]


The table is sorted in descending order of the total contribution of the object files to the binary size. The columns indicate memory types and output sections as detailed in the Size Summary.

For example, we can see that the file ``x509_crt_bundle.S.o`` contributed 67,810 bytes to the total firmware size, all as ``.rodata`` in flash. Therefore we can guess that this application is using the :doc:`/api-reference/protocols/esp_crt_bundle` feature and not using this feature would save at last this many bytes from the firmware size.

Some of the object files are linked from binary libraries and therefore you will not find a corresponding source file. To locate which component a source file belongs to, it is generally possible to search in the ESP-IDF source tree or look in the :ref:`linker-map-file` for the full path.

Comparing Two Binaries
^^^^^^^^^^^^^^^^^^^^^^

When making changes that impact binary size, you can use the IDF Size tool to analyze the precise differences in size. The ``--diff`` option can be used with all previously mentioned sub-commands, allowing you to specify a path to a project build for comparison with the current project.

For example to compare two ``hello_world`` project builds, follow these steps. First, create two copies of the ``hello_world`` project directory. Name the first project directory ``hello_world_Og``. This project will use the default :ref:`CONFIG_COMPILER_OPTIMIZATION` compiler optimization setting ``Debug (-Og)`` and will serve as the ``REFERENCE`` project. Name the second project directory ``hello_world_Os``. This project will use the ``Optimize for size (-Os)`` setting, which can be enabled using ``idf.py menuconfig``. This will be the ``CURRENT`` project. Build both projects. Then, from within the ``hello_world_Os`` project directory, run the following command:


.. code-block:: bash

   $ idf.py size --diff ../hello_world_Og

    CURRENT   project file: "hello_world_Os/build/hello_world.map"
    REFERENCE project file: "hello_world_Og/build/hello_world.map"
    Difference is counted as CURRENT - REFERENCE, i.e. a positive number means that CURRENT is larger.
                                   Memory Type Usage Summary
    ┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
    ┃ Memory Type/Section ┃ Used [bytes] ┃     Used [%] ┃ Remain [bytes] ┃  Total [bytes] ┃
    ┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
    │ Flash Code          │ 74498  -6168 │  2.23  -0.18 │ 3267806  +6168 │ 3342304      0 │
    │    .text            │ 74498  -6168 │  2.23  -0.18 │                │                │
    │ IRAM                │ 45539  -6296 │ 34.74   -4.8 │   85533  +6296 │  131072      0 │
    │    .text            │ 44511  -6296 │ 33.96   -4.8 │                │                │
    │ Flash Data          │ 35784  -2440 │  0.85  -0.06 │ 4158488  +2440 │ 4194272      0 │
    │    .rodata          │ 35528  -2440 │  0.85  -0.06 │                │                │
    │ DRAM                │ 10844   -392 │   6.0  -0.22 │  169892   +392 │  180736      0 │
    │    .data            │  8612   -376 │  4.76  -0.21 │                │                │
    │    .bss             │  2232    -16 │  1.23  -0.01 │                │                │
    └─────────────────────┴──────────────┴──────────────┴────────────────┴────────────────┘
    Total image size: 164432 -15280 bytes (.bin may be padded larger)

In addition to the previously mentioned Size Summary example, each column now also shows the size differences. Each difference is shown as ``CURRENT - REFERENCE``, meaning the current project sizes minus the sizes in the project specified with the `--diff` option. In this example, the final binary image of the ``hello_world_Os`` project is 15,280 bytes smaller than that of the ``hello_world_Og`` project. Additionally, the ``hello_world_Os`` project uses 6,168 bytes less in `Flash Code` memory, leaving 6,168 bytes more available in ``Flash Code``, with no difference in the total available memory.

You can also use the diff mode to generate a table showing the differences at the component level (static library archive):

.. code-block:: bash

   $ idf.py size-components --diff ../hello_world_Og

Additionally, at the level of each individual source file:

.. code-block:: bash

   $ idf.py size-files --diff ../hello_world_Og

.. _idf-size-linker-failed:

Showing Size When Linker Fails
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If too much static memory is allocated, the linker will fail with an error such as ``DRAM segment data does not fit``, ``region `iram0_0_seg' overflowed by 44 bytes``, or similar.

In these cases, ``idf.py size`` will also fail. However, you can run ``idf_size.py``, which is a convenient wrapper that allows you to call ``esp-idf-size`` directly from within the ESP-IDF environment and see the partial static memory usage. The ``idf_size.py`` script requires a link map file as an argument, which is located in the project's build directory as ``<projectname>.map``.

.. code-block:: bash

    $ idf_size.py <projectname>.map
    warning:  DRAM overflow detected!: output section or its part .dram0.bss(addr: 1073422848, size: 2240) does not fit into any memory region and will be assigned to the preceding dram0_0_seg memory region
    warning:  DRAM overflow detected!: output section or its part .dram0.data(addr: 1073414144, size: 8704) does not fit into any memory region and will be assigned to the preceding dram0_0_seg memory region
                                Memory Type Usage Summary
    ┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
    ┃ Memory Type/Section ┃ Used [bytes] ┃ Used [%] ┃ Remain [bytes] ┃ Total [bytes] ┃
    ┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
    │ Flash Code          │        79759 │     2.39 │        3262545 │       3342304 │
    │    .text            │        79759 │     2.39 │                │               │
    │ IRAM                │        51106 │    38.99 │          79966 │        131072 │
    │    .text            │        50079 │    38.21 │                │               │
    │    .vectors         │         1027 │     0.78 │                │               │
    │ Flash Data          │        38576 │     0.92 │        4155696 │       4194272 │
    │    .rodata          │        38320 │     0.91 │                │               │
    │    .appdesc         │          256 │     0.01 │                │               │
    │ DRAM                │        10944 │        0 │         -10944 │             0 │
    │    .data_overflow   │         8704 │        0 │                │               │
    │    .bss_overflow    │         2240 │        0 │                │               │
    └─────────────────────┴──────────────┴──────────┴────────────────┴───────────────┘
    Total image size: 178145 bytes (.bin may be padded larger)

Sections that do not fit into the memory region will have the suffix ``_overflow``.

.. _esp-idf-size: https://github.com/espressif/esp-idf-size
