idftool
The ultimate CLI tool for interacting with Espressif devices. Built on
esptool and aware of the ESP-IDF
partition table: flash apps, switch OTA slots, and read or write partitions by
name, without working out offsets by hand.
Highlights
Device selection on connection
No more guessing which device is on which port. Run any command without -p
and idftool lists the connected devices and asks which to use:
$ idftool monitor
? Select device (↑↓ move · ↵ select · p probe · r refresh · k kill · q quit)
» /dev/cu.usbmodem11401 ESP USB-Serial/JTAG 7c:2c:67:92:79:c0
/dev/cu.usbmodem2101 ESP USB-Serial/JTAG b8:f8:62:49:ea:14
/dev/cu.PL2303G-USBtoUART10 PL2303GT
✎ Enter a port manually…
↻ Refresh
✕ Quit
Pick one, and it tells you how to skip the question next time:
Device: /dev/cu.usbmodem11401 — ESP USB-Serial/JTAG · 7c:2c:67:92:79:c0
Re-run with: idftool -p /dev/cu.usbmodem11401 monitor
or: idftool -m 7c:2c:67:92:79:c0 monitor
--- esp-idf-monitor 1.10.0 on /dev/cu.usbmodem11401 115200
--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H
The -m form finds the board by its MAC address, wherever it's plugged in.
It works with idf.py too. Alias it, and every flash or monitor asks which
device to use:
alias idf.py='idftool idf.py'
Firmware flashing
Flash to the default (factory) or next available (OTA) app partition, with no offsets to memorise. An OTA flash switches to the new slot the way a real update would, and only the sectors that changed are rewritten.
idftool factory build/app.bin
idftool ota build/app.bin
idftool set-boot ota_1
Partition-name addressing
Read, write, erase, or hex-dump a partition by name, or a slice of one:
idftool read nvs nvs.bin
idftool write storage build/spiffs.bin
idftool view 'log[-0x1000:]'
Safety checks
Everything is checked before flash is touched:
- Data has to fit the partition it's written to.
- Apps have to be valid images, built for the connected chip.
- A file name given where a partition name belongs is caught before connecting, with the corrected command.
Bundles and images
Pack several partitions (and optionally the partition table) into one ZIP and flash them in one command, or dump and restore a whole flash image.
idftool dump-bundle backup.zip
idftool write-bundle release.zip
Filesystems and NVS
Build FAT, littlefs, or SPIFFS images from a directory and flash them, or pull them off the device. The filesystem type comes from the partition table, so you don't need to say which. Generate NVS from CSV, read a key into a shell, or change one on a live device.
idftool write-fs storage assets/
serial=$(idftool get-nvs nvs storage:serial)
idftool set-nvs nvs storage:serial=SN-0001
Contributing
See CONTRIBUTING.md.
1 maintainer
Metadata
1 maintainer
Release files for idftool 1.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| idftool-1.4.0.tar.gz | 477.8 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| idftool-1.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 601.6 kB
Release files / idftool-1.4.0.tar.gz
| Download URL | idftool-1.4.0.tar.gz |
|---|---|
| Size | 477.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
20e73a7c1dfa8356d08aa3c9fb35440fc7b6be0e83bb5ad68e6a35c51a24c744
|
|
BLAKE2b-256 checksum How to use checksums |
1b9efd87725eb7c8953cbcba0f4282406edda7d20d20bd9e6f187a912bc5f319
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logRelease files / idftool-1.4.0-py3-none-any.whl
| Download URL | idftool-1.4.0-py3-none-any.whl |
|---|---|
| Size | 123.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
10c3bfbf4b1f9ac751d22714ec320490983369e9c5001d2d64666bbdf3f1ea7b
|
|
BLAKE2b-256 checksum How to use checksums |
d2d33ad8b364315ed23ed86288a9720e5663096d10308f9fa9263ca813517d29
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logSecurity for idftool 1.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for idftool-1.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
