この記事のポイント
- ESP-IDFはArduinoより低レベルで、ESP32のすべての機能（Wi-Fi・BLE・FreeRTOS等）を使える公式フレームワークです
- Ubuntu 24.04 では前提パッケージを
apt-get install1コマンドでそろえられます（Python 3.12.3 / cmake 3.28.3 / git 2.43.0 — いずれもESP-IDF要件を余裕でクリア） - Ubuntu 24.04 は PEP 668 制限 があり
pip installが失敗します。ESP-IDF は内部で venv を自動作成するので実害はありませんが、手動でpipを使うときは--break-system-packagesか venv が必要です - ツールチェーン（
install.sh）は初回だけで約1.5GB ダウンロード。2回目以降は. export.shだけで済みます - 本記事では Ubuntu 24.04（Docker公式イメージ）で実際にパッケージをインストールし、バージョンを実測しています
動作確認済み環境
本記事のパッケージインストール手順は Ubuntu 24.04 LTS (Noble Numbat) で実測済みです。前提パッケージのバージョン確認は Docker 公式イメージ ubuntu:24.04 で行っています。ESP-IDF v5.x（最新安定版）を対象にしています。
ESP-IDFとは？Arduinoとどこがちがうのか
ESP32 の開発環境として最初に名前が出るのは Arduino IDE ですが、本格的な製品を作るときには ESP-IDF（Espressif IoT Development Framework） を使うのが標準です。Espressif が公式に提供しているフレームワークで、ESP32 のすべての機能にアクセスできます。
Arduino との最大のちがいは「何がコントロールできるか」です。
| 比較項目 | Arduino（esp32-arduino） | ESP-IDF |
|---|---|---|
| 難易度 | 低い（C++、setup/loop で書ける） | 中〜高（C、FreeRTOSの知識が必要） |
| Wi-Fi/BLE の設定粒度 | ライブラリに隠蔽されている | パラメータを細かくコントロール可能 |
| FreeRTOS 操作 | 間接的にしか使えない | タスク・キュー・セマフォを直接操作可 |
| 省電力制御 | 限定的 | Deep Sleep や ULP を細かく設定可 |
| 公式サポート | サードパーティ（Espressif は関与） | Espressif 公式（ファームウェアと同一チーム） |
「Lチカや温度センサーなら Arduino でじゅうぶん。Wi-FiのTLS接続を細かく設定したい、FreeRTOSのタスクを自分で管理したい、量産品に使いたい」—そういうときに ESP-IDF が必要になります。
ビルドシステムは idf.py というPythonスクリプトで、内部で CMake + Ninja が動きます。IDE に縛られず VS Code や Vim から使えるのも利点です。
前提パッケージをインストールする
ESP-IDF が動作するために必要なパッケージを Ubuntu 24.04 にインストールします。Espressif の公式ドキュメントに記載されている一覧を、そのまま apt-get install に渡します。
$ sudo apt-get install -y git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0
Reading package lists… Done
Building dependency tree… Done
Setting up git (1:2.43.0-1ubuntu7.3) …
Setting up cmake (3.28.3-1build7) …
Setting up python3 (3.12.3-0ubuntu2.1) …
Setting up python3-pip (24.0+dfsg-1ubuntu1.3) …
Setting up ninja-build (1.11.1-2) …
Setting up dfu-util (0.11-1) …
インストール後にバージョンを確認しておきます。ESP-IDF は Python 3.8+ と cmake 3.16+ を要求していますが、Ubuntu 24.04 の標準パッケージはどちらもクリアしています。
git version 2.43.0
Python 3.12.3
cmake version 3.28.3
1.11.1
Ubuntu 22.04 との差も確認しました。22.04 では Python 3.10.12 / cmake 3.22.1 が入りますが、どちらも ESP-IDF の要件を満たします。新しい環境を作るなら 24.04 の方が各ツールが新しく、長期サポートも2029年4月まであるので安心です。
Ubuntu 24.04 の PEP 668 制限について
Ubuntu 24.04 では pip3 install をシステム全体に実行しようとすると「externally-managed-environment」エラーが出ます（PEP 668 という仕様変更）。ESP-IDF の install.sh は内部で venv を自動作成するので、この制限は ESP-IDF のセットアップには影響しません。ただし手動でグローバルに pip インストールしたい場合は --break-system-packages を付けるか、venv 内で実行してください。
ESP-IDF本体をクローンする
以降の手順について
クローン・ツールチェーン導入・ビルド・書き込みの各セクションでは、公式ドキュメントに基づく典型的な実行例を示しています。実際の出力はクローンした ESP-IDF のバージョンやターゲットにより異なります。前提パッケージのインストール手順（Python 3.12.3 / cmake 3.28.3 など）は Ubuntu 24.04 Docker で実測済みです。
ESP-IDF はすべて GitHub 上で公開されています。--recursive を付けてサブモジュールも一緒にクローンします。サブモジュールが大量にあるので、初回は数分かかります。
$ git clone –recursive https://github.com/espressif/esp-idf.git
Cloning into ‘esp-idf’…
Receiving objects: 100% (…) done.
Submodule ‘components/bootloader/subproject/…’ (…)
Submodule ‘components/esp_wifi/lib’ (…)
…
Submodule path ‘…’: checked out ‘…’
特定のバージョンを使いたい場合は、クローン後にブランチかタグをチェックアウトします。
$ git checkout v5.4
$ git submodule update –init –recursive
Submodule path ‘…’: checked out ‘…’
安定版で使うなら最新の v5.x タグを選ぶのが無難です。master ブランチは開発中の機能が入るため、実機で使うには向きません。
ツールチェーンをインストールする（install.sh）
ソースコードをクローンしただけでは idf.py build はできません。ESP32用のクロスコンパイラ（xtensa-gcc）や OpenOCD などをインストールするために install.sh を実行します。
Installing ESP-IDF tools
Selected targets are: esp32
Installing tools: xtensa-esp-elf, xtensa-esp-elf-gdb, esp32ulp-elf, openocd-esp32, …
Downloading xtensa-esp-elf-…
Extracting xtensa-esp-elf-…
All done! You can now run:
. ./export.sh
引数に esp32 と書くのがポイントです。ESP32-S2・S3・C3 を使う場合は esp32s2 / esp32s3 / esp32c3 を並べて渡せます。すべてのターゲットを入れたいときは all を指定します（容量が大きくなります）。
Selected targets are: esp32, esp32s3
Installing tools …
ダウンロードされるファイルは ~/.espressif/ 以下に展開されます。初回は合計で約1〜1.5GB 必要なので、ディスク残量を事前に確認しておきましょう。
最初に all を指定したら思いのほか時間がかかりました。使うターゲットだけ指定する方が現実的です。後から追加する場合は再度 install.sh を実行すれば差分だけ取ってきます。
環境変数を設定する（export.sh）
install.sh が完了したら、作業するたびに export.sh を読み込んで環境変数を設定します。これを忘れると idf.py: command not found になります。
Detecting the Python interpreter
Checking “python3” …
Python 3.12.3
Added IDF_PATH, PATH, and IDF_PYTHON_ENV_PATH to environment
$ idf.py –version
ESP-IDF v5.x ← クローンしたブランチ/タグのバージョンが表示される
毎回 cd ~/esp/esp-idf && . export.sh と打つのが面倒なら、~/.bashrc にエイリアスとして登録しておくと楽です。
$ source ~/.bashrc
$ get_idf
Added IDF_PATH, PATH, and IDF_PYTHON_ENV_PATH to environment
次回のターミナル起動からは get_idf と打つだけです。
hello_worldをビルド・書き込みする
環境が整ったので、ESP-IDF に付属のサンプルプロジェクトをビルドしてみます。hello_world がちょうど良いサイズです。
手順1：サンプルプロジェクトをコピーする
$ cd ~/esp/hello_world
$ ls
CMakeLists.txt main/ README.md sdkconfig.defaults
esp-idf/ ディレクトリの中に直接プロジェクトを作るのは避けた方が良いです。IDF 本体をアップデートするときにファイルが競合します。
手順2：ターゲットを設定してビルドする
Adding “set-target” dependency: idf_py_actions.create_project_actions
Set target ‘esp32’.
$ idf.py build
Executing action: all (aliases: build)
Running cmake in directory /home/user/esp/hello_world/build
Compiling main/hello_world_main.c
Linking …/hello_world.elf
Project build complete. To flash, run:
idf.py -p /dev/ttyUSB0 flash
ビルドが通れば build/ ディレクトリに hello_world.bin と hello_world.elf が生成されます。
手順3：ESP32に書き込む
USB で ESP32 を接続し、シリアルポートを確認します。多くの場合 /dev/ttyUSB0 か /dev/ttyACM0 です。
/dev/ttyUSB0
$ idf.py -p /dev/ttyUSB0 flash monitor
Flashing binaries to ESP32 chip on /dev/ttyUSB0 (app @ 0x10000)…
Flash will take about 3 seconds.
Hash of data verified.
— idf_monitor on /dev/ttyUSB0 115200 —
Hello world!
This is esp32 chip with 2 CPU core(s), WiFi/BT/BLE
Restarting in 10 seconds…
「Hello world!」が出たらセットアップ成功です。monitor 終了は Ctrl + ] です。
Permission denied エラーが出る場合
/dev/ttyUSB0: Permission denied が出た場合、現在のユーザーが dialout グループに入っていません。sudo usermod -aG dialout $USER を実行して、一度ログアウト→再ログインしてください。
よくあるエラーと解決策
①externally-managed-environment（pip インストール失敗）
Ubuntu 24.04 で pip install を直接実行すると以下のエラーが出ます。
error: externally-managed-environment
This environment is externally managed
hint: See PEP 668 for the detailed specification.
ESP-IDF 本体の install.sh は venv を使うのでこのエラーは出ません。手動でパッケージを入れたい場合は venv を使ってください。
$ source ~/myenv/bin/activate
(myenv) $ pip install somepackage
Successfully installed somepackage-x.x.x
②git submodule の取得が止まる
git clone --recursive の途中でネットワークエラーになった場合、git submodule update --init --recursive を再実行すれば続きから取れます。
③idf.py: command not found
export.sh の読み込みを忘れています。. ~/esp/esp-idf/export.sh を実行してください。
④cmake: version 3.xx required, but 3.xx was found
Ubuntu 20.04 などの古い環境で発生します。Ubuntu 24.04 に移るか、pip install cmake（venv内）でより新しい cmake を入れてください。Ubuntu 24.04 の cmake 3.28.3 ならこのエラーは出ません。
⑤A fatal error occurred: Failed to connect to ESP32
書き込み中にESP32が反応しない場合の対処法です。
- BOOTボタンを押しながら
flashを実行する（手動リセット） - シリアルケーブルがデータ通信対応か確認する（充電専用ケーブルは不可）
--baud 115200に下げてみる
まとめ
Ubuntu 24.04 での ESP-IDF セットアップをまとめます。
- 前提パッケージは
apt-get install1コマンドで揃います。Ubuntu 24.04 なら Python 3.12.3 / cmake 3.28.3 / git 2.43.0 が入り、いずれも ESP-IDF の要件を余裕でクリアしています git clone --recursiveの後、install.sh esp32でツールチェーンを入れるのが最初の山場です。1〜1.5GBのダウンロードが必要なので、ネットワーク環境の良いところで実行してください- 毎回のセッション開始時に
. export.shを実行するか、~/.bashrcにエイリアスを登録しておくと便利です - Ubuntu 24.04 の PEP 668 制限は ESP-IDF の動作に影響しませんが、手動で
pip installする場合は venv を使うことを覚えておきましょう
環境が動けば、あとは idf.py build → idf.py flash → idf.py monitor のサイクルです。最初は hello_world で動作を確認してから、Wi-FiやBLEを使うサンプルに進むと理解が深まります。
ESP-IDFに慣れたら、もっと複雑なことをするためにクラウドやVPSで開発環境を管理したくなることがあります。その際は下のリンクも参考にしてみてください。
コメント