esptool

Espressif 칩의 serial bootloader와 통신해 flash read/write, erase, image 변환을 수행하는 Python 기반 CLI 도구. ESP32/ESP8266 계열 펌웨어 플래싱과 flash 점검에 자주 사용된다.

Summary

esptool은 Python 패키지이면서 동시에 standalone CLI로 사용된다.
이 페이지는 로컬 바이너리가 없는 상태에서 2026-06-28 기준 Espressif 공식 문서를 확인해 작성했다.
SDK/framework 안에 포함된 esptool은 framework가 기대하는 major version을 따르는 편이 안전하다.

Install

공식 문서는 최신 esptool 사용 시 Python 3.10 이상을 요구한다. Python 3.7~3.9는 v4.x, Python 2.7/3.4~3.6은 v3.3.* 계열을 사용하라고 안내한다.

# 기본 설치
pip install esptool
 
# pip 직접 실행이 안 될 때
python -m pip install esptool
pip3 install esptool
 
# 가상환경 사용
python -m venv esptoolenv
source esptoolenv/bin/activate
pip install esptool
 
# 업그레이드
pip install --upgrade esptool
 
# 모듈 형태 실행
python -m esptool version

공식 문서는 system-wide install보다 virtual environment 사용을 권장한다.
Python 없이 쓰고 싶다면 GitHub Releases의 pre-built binary도 사용할 수 있지만, 지원 OS/아키텍처와 제약을 먼저 확인한다.
framework 내부 도구라면 framework 문서에 맞춰 업그레이드하고, 임의 upgrade가 필요하면 major version 호환성을 먼저 확인한다.

Usage

esptool [OPTIONS] COMMAND [ARGS]...

esptool [OPTIONS] COMMAND [ARGS]…
esptool –chip ESP32 –port /dev/ttyUSB0 –baud 460800 write-flash OFFSET FILE…
esptool flash-id: SPI flash ID 읽기
esptool read-mac: built-in MAC address 읽기
esptool write-flash OFFSET FILE…: flash에 binary 기록
esptool read-flash ADDRESS SIZE OUTFILE: flash 내용 덤프
esptool erase-flash: flash 전체 erase
esptool erase-region ADDRESS SIZE: flash 일부 영역 erase
esptool image-info FILE.bin: image header / segment 정보 확인
esptool merge-bin -o OUTFILE OFFSET FILE…: 여러 image 병합
esptool elf2image APP.elf: ELF를 flashable binary로 변환

Options

–chip CHIP: 대상 칩 지정. 예: ESP32, ESP32-S3
–port PORT: serial port 지정. 예: /dev/ttyUSB0, COM5
–baud RATE: serial baudrate 지정
–before default-reset|no-reset|no-reset-no-sync: 작업 전 reset / sync 동작 제어
–after hard-reset|no-reset|no-reset-stub: 작업 후 reset 동작 제어
–no-stub: stub loader 업로드 비활성화
–port-filter TYPE=VALUE: VID/PID/name/serial 기준 포트 autodetection 필터링

Examples

# 설치 확인
esptool version
python -m esptool version
 
# flash ID 확인
esptool --port /dev/ttyUSB0 flash-id
 
# MAC 주소 읽기
esptool --chip ESP32 --port /dev/ttyUSB0 read-mac
 
# 앱/부트로더/파티션 테이블 플래시
esptool --chip ESP32 --port /dev/ttyUSB0 --baud 460800 \
  write-flash 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 app.bin
 
# flash 전체 덤프
esptool --port /dev/ttyUSB0 read-flash 0 0x200000 flash.bin
 
# flash 전체 erase
esptool --port /dev/ttyUSB0 erase-flash
 
# 이미지 정보 확인
esptool image-info app.bin
 
# 여러 바이너리 병합
esptool --chip ESP32 merge-bin -o merged-flash.bin \
  0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 app.bin

Troubleshooting

esptool: command not found: virtual environment 활성화 여부 또는 python -m esptool 형태 실행을 먼저 확인
포트를 못 찾으면 –port 지정, lsusb, dmesg로 USB-serial 장치 이름 확인
auto reset이 실패하면 –before no-reset 또는 boot 버튼을 사용한 수동 bootloader 진입이 필요할 수 있다
framework 번들 버전을 무시하고 최신판으로 올리면 toolchain 호환성이 깨질 수 있다
erase-flash 는 NVS/설정/앱을 모두 지울 수 있으므로 destructive 작업으로 취급한다

Compatibility

이 작업 환경에는 esptool 바이너리가 없어 로컬 –help 원문은 캡처하지 못했다.
공식 문서 기준 최신판은 Python 3.10+를 요구하며, 구형 Python은 별도 major/minor 계열 사용이 필요하다.
pre-built binary는 편하지만 Python module import 용도로는 쓸 수 없다.

Help

esptool --help

Local `esptool` binary was not available in this workspace on 2026-06-28.
 
Verified from official Espressif docs:
  * installation via `pip install esptool`
  * `python -m esptool` module execution
  * commands: flash-id, read-mac, write-flash, read-flash, erase-flash, erase-region,
    image-info, merge-bin, elf2image
  * global options: --chip, --port, --baud, --before, --after, --no-stub, --port-filter

History

codex:: 2026-06-28 Created esptool page with official installation guidance, flashing examples, and version compatibility notes.

목차