Keep long-term compatibility for `_` command style and provide an env variable to suppress deprecation warnings (ESPTOOL-1219)

[TinyuZhao]

Is your feature request related to a problem?

First of all, thank you for your continuous work on esptool and the improvements introduced in v5.
I am an engineer who frequently switches between multiple development environments, including different versions of ESP-IDF and Arduino (PlatformIO and Arduino IDE). Because these environments bundle different versions of esptool, the recent change from underscore (_) command/option names to dash (-) names has caused some practical compatibility issues.

Background of the issue

• Newer Arduino builds already include esptool v5.x, where old commands with _ still work but print deprecation warnings.
• Older Arduino / ESP-IDF environments only support the old _ form.
• This means I cannot use the new - style universally without breaking older environments.
• At the same time, keeping the _ style causes v5 to output warnings every time, which becomes noisy in daily use.

Because I frequently jump between these environments (and many automation scripts rely on consistent commands), this change brings noticeable inconvenience.

Describe the solution you'd like

I would like to propose two enhancements:

1. Keep long-term compatibility for underscore (_) command and option names

Even if they remain marked as “deprecated”, keeping them functional permanently would greatly improve compatibility across mixed-toolchain environments and avoid breaking older Arduino/IDF setups.

2. Add an environment variable to disable the deprecation warnings

Something like:

ESPTOOL_HIDE_DEPRECATED_WARNING=1

or any similar flag.

This would:

• Reduce console noise for users who must continue using old-style commands for compatibility reasons
• Avoid modifying many scripts just to silence harmless warnings
• Keep default behavior unchanged for most users

Additional context

Many users work with mixed environments (IDF, Arduino, PlatformIO, CI systems). Since these ecosystems evolve at different speeds and bundle different versions of esptool, it’s currently impossible to use a single consistent command style across all of them.

Having a compatibility switch + warning suppression would significantly improve workflow for engineers dealing with legacy and new environments simultaneously.

[github-actions]

Hi @TinyuZhao! Please be aware that (1) the following suggestions are generated by a bot and haven't been fact-checked by Espressif Systems, (2) burning eFuses and enabling security features are irreversible operations and can damage your ESP32 device. We hope that this message will help you until an Espressif Engineer looks at your issue.

---

Thank you for your thoughtful feedback and for describing the real-world challenges of working across mixed ESP-IDF, Arduino, and PlatformIO environments.

Current Status (as of esptool v5.x):

• The transition from underscore (_) to dash (-) in command and option names is a breaking change in esptool v5.x. Old underscore-style commands are still supported for now, but they print deprecation warnings. This is intended as a temporary compatibility measure; the documentation and changelogs clearly state that support for underscore commands will be removed in a future major release. Users are advised to migrate scripts and tooling to the new dash style as soon as possible to avoid future breakage esptool v5 Migration Guide esptool v5.0.0 Release Notes.

• There is currently no environment variable or documented method to suppress the deprecation warnings for underscore commands in esptool v5.x. The warnings are always printed when deprecated forms are used.

Regarding Your Suggestions:

1. Long-term compatibility for underscore commands:
   The official documentation and release notes indicate that underscore-style commands are only temporarily supported and will be removed in a future major release. There is no commitment to keep them indefinitely for long-term compatibility. Users are encouraged to update their scripts and workflows to use the dash style to ensure future compatibility.

2. Environment variable to suppress deprecation warnings:
   As of the latest available documentation and changelogs, there is no support for an environment variable (such as ESPTOOL_HIDE_DEPRECATED_WARNING) or any other mechanism to suppress these deprecation warnings. This feature is not currently available or planned according to the public sources.

Summary:

• Underscore commands are deprecated and will be removed in a future release; there is no guarantee of long-term support.
• There is no built-in way to suppress deprecation warnings via an environment variable or similar mechanism at this time.

If you would like to see these features considered, it would be best to open a feature request (which you have done) so the maintainers can evaluate the impact and feasibility for future versions.

References:

• esptool v5 Migration Guide – Command and Option Renaming
• esptool v5.0.0 Release Notes

If you need further clarification or have additional questions, please let me know!

[dobairoland]

Thank you for writing up your use cases but I'm sorry to tell you that we won't consider to implement this request.

I understand your inconvenience but such removal of deprecation warnings would just delay these issues and requests. Users will set the environment variable and when it becomes obsolete (because the old commands are no longer available) will just ask a similar delay of the change.

We consider the current solution the long term compatibility - because beside the warnings there is no breaking change. "Long term" because I don't assume esptool would drop them earlier than in the next 1 or 2 years.

Those SDKs you mention bundle different esptools for a reason. They are tested with those versions and might not be compatible with the other one - different arguments, missing features, and similar. I believe each of them have their own copy of esptool which means they are hiding this burden from the user.

But if you prefer to build with different SDK versions and flash with one esptool then I would suggest to use the newest version and install it as per https://docs.espressif.com/projects/esptool/en/latest/esp32/installation.html#virtual-environment-installation into a virtual environment and you will not receive any warnings which bothers you. The newest esptool can flash all chips which the older version could do (only some beta chip supports are dropped which were replaced by mass production versions).

[TinyuZhao]

Thank you for your suggestion. I'll try embracing the new version.