When to Use the `--no-erase` Option in esp_flasher to Preserve Existing Flash Data

Use the --no-erase flag when flashing firmware to retain existing non-volatile storage data, Wi-Fi credentials, or custom partition contents while updating only specific firmware regions on ESP devices.

The jason2866/esp_flasher tool defaults to erasing the entire flash memory before writing new firmware to ensure a clean slate. However, when working with ESP32 or ESP8266 devices that store persistent configuration data, you can skip the full erase to preserve existing information while updating the application code.

How the --no-erase Flag Works in the Source Code

In esp_flasher/__main__.py, the decision to erase flash memory is controlled by a conditional check at lines 17-22. When the --no-erase argument is absent, the code executes esptool.erase_flash(stub_chip, mock_args), which wipes the entire chip before writing the new binary. The CLI flag itself is defined at line 72 as a boolean argument (action="store_true") that sets args.no_erase=True when the user includes it in the command.

When --no-erase is specified, the tool bypasses the esptool.erase_flash() call entirely and proceeds directly to esptool.write_flash(), leaving existing data partitions untouched.

When to Use --no-erase to Preserve Existing Flash Data

Retaining NVS and User Configuration Data

Many ESP applications store calibration coefficients, Wi-Fi credentials, and device-specific settings in Non-Volatile Storage (NVS) or dedicated data partitions. Use --no-erase when flashing new firmware to keep these critical settings intact, preventing the need to reconfigure the device after every update cycle.

Partial Firmware Updates

When you are only updating the application binary and not modifying the bootloader or partition table structure, skipping the full erase reduces flash wear and accelerates the programming process. This approach is safe when the new binary size and location do not conflict with existing data partitions.

Custom Partition Layouts

If your device uses a custom partition table and you are flashing only specific regions (such as updating a single OTA slot while preserving the other), the --no-erase option allows surgical updates without disrupting unrelated flash sectors.

Rapid Development Iterations

During debugging sessions, developers often flash incremental builds repeatedly. Using --no-erase eliminates the time-consuming full erase cycle, allowing faster iteration while preserving test configurations and network credentials stored in flash memory.

When to Avoid the --no-erase Option

Do not use this flag when changing the partition table layout or updating the bootloader, as existing data structures may become incompatible with the new firmware organization. Fresh devices or chips with corrupted flash require a full erase to ensure a clean, predictable state before programming.

Additionally, avoid --no-erase if you are uncertain whether the existing flash data is compatible with the new firmware version, as mismatched configuration data can lead to undefined behavior or boot failures.

Command Examples for Preserving Flash Data

Flashing While Preserving NVS Data

esp_flasher --port /dev/ttyUSB0 --esp32 --no-erase my_firmware.bin

This command parses the --no-erase flag, setting args.no_erase=True in esp_flasher/__main__.py. The execution path at lines 17-22 skips the esptool.erase_flash() call, leaving existing data partitions untouched while writing the new firmware binary.

Default Full Erase Behavior

esp_flasher --port /dev/ttyUSB0 --esp32 my_firmware.bin

Without the --no-erase flag, args.no_erase remains False. The tool calls esptool.erase_flash() before writing, wiping the entire flash memory including any stored Wi-Fi credentials or calibration data.

Partial Update with Specific Offset

esp_flasher --port /dev/ttyUSB0 --esp32 --no-erase --input app.elf my_firmware.bin

This example preserves the NVS and OTA data partitions while flashing only the application binary. The --no-erase flag prevents wiping unrelated flash sectors, making it ideal for incremental updates during development.

Summary

• The --no-erase option in jason2866/esp_flasher skips the esptool.erase_flash() call defined in esp_flasher/__main__.py lines 17-22.
• Use this flag to preserve NVS data, Wi-Fi credentials, and custom partition contents during firmware updates.
• Avoid this flag when changing partition tables, updating bootloaders, or flashing brand-new devices that require a clean slate.
• The CLI argument is defined at line 72 of esp_flasher/__main__.py as a boolean flag that triggers conditional erase logic.

Frequently Asked Questions

Does using --no-erase affect firmware writing speed?

Yes, using --no-erase typically reduces total programming time by eliminating the full chip erase cycle, which can take several seconds depending on flash size. However, if the target sectors were not previously erased, the write operation may still proceed normally since esptool.write_flash() handles sector erasing automatically during the write process.

Can I update the bootloader while using --no-erase?

You should not use --no-erase when updating the bootloader or changing the partition table layout. The existing data partitions may rely on the previous bootloader's configuration, and mismatched structures can cause boot failures or data corruption. A full erase ensures all flash sectors align with the new firmware structure.

Will existing data remain valid if the partition table changes?

Existing data will likely become invalid or inaccessible if the partition table changes while using --no-erase. The firmware locates data partitions by their offsets defined in the partition table; if these offsets shift in the new firmware but the old data remains at previous locations, the application cannot locate its configuration data.

Is --no-erase safe for production deployment?

--no-erase is safe for production deployment only when you are certain that the existing flash data is compatible with the new firmware version and the partition layout remains unchanged. It is particularly useful for over-the-air (OTA) style updates via serial where you want to preserve user configurations, but ensure your deployment pipeline validates that the target devices have compatible existing data structures.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}