diff --git a/components/esptool_py/Kconfig.projbuild b/components/esptool_py/Kconfig.projbuild
index b81a69ab8c..923d4b9d77 100644
--- a/components/esptool_py/Kconfig.projbuild
+++ b/components/esptool_py/Kconfig.projbuild
@@ -155,7 +155,7 @@ menu "Serial flasher config"
         default "64MB" if ESPTOOLPY_FLASHSIZE_64MB
         default "128MB" if ESPTOOLPY_FLASHSIZE_128MB
 
-    config ESPTOOLPY_FLASHSIZE_DETECT
+    config ESPTOOLPY_HEADER_FLASHSIZE_UPDATE
         bool "Detect flash size when flashing bootloader"
         default n
         help
diff --git a/components/esptool_py/project_include.cmake b/components/esptool_py/project_include.cmake
index 3af1601608..88378071bf 100644
--- a/components/esptool_py/project_include.cmake
+++ b/components/esptool_py/project_include.cmake
@@ -63,7 +63,7 @@ if(min_rev)
     unset(min_rev)
 endif()
 
-if(CONFIG_ESPTOOLPY_FLASHSIZE_DETECT)
+if(CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE)
     # Set ESPFLASHSIZE to 'detect' *after* esptool_elf2image_args are generated,
     # as elf2image can't have 'detect' as an option...
     set(ESPFLASHSIZE detect)
diff --git a/docs/en/migration-guides/tools.rst b/docs/en/migration-guides/tools.rst
index 3b5103cf5b..445bdc8419 100644
--- a/docs/en/migration-guides/tools.rst
+++ b/docs/en/migration-guides/tools.rst
@@ -35,3 +35,8 @@ Deprecated commands
      - erase-otadata
    * - read_otadata
      - read-otadata
+
+Esptool
+-------
+
+The CONFIG_ESPTOOLPY_FLASHSIZE_DETECT option has been renamed to :ref:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE` and it is disabled by default. New and existing projects migrated to ESP-IDF v5.0 will have to set :ref:`CONFIG_ESPTOOLPY_FLASHSIZE`. If this is not possible because the flash size is not known at build time then :ref:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE` can be enabled but this will have the consequence of not appending a SHA256 digest after the image in order that the binary header could be updated with the flash size during flashing without invalidating the digest.