ガイド · 読了まで12分

ESP32のボードパッケージがインストールできない:Arduino IDEのエラー解決法

Arduino IDEでESP32のボードパッケージをインストールできないときの対処法です。正しいURLの確認から、Error downloading、タイムアウト、ウイルス対策ソフト、プロキシ、古いファイルの掃除、オフラインインストールまで解説します。

Arduino IDEでESP32のボードパッケージがインストールできないというのは、ESP32を始めるときにいちばんよくぶつかる壁です。ボードマネージャにesp32が出てこない、インストールが「Error downloading」で途中で止まる、何分も待ったあげくタイムアウトになる、といった具合です。原因はほぼ必ず次の5つのどれかです。ボードマネージャのURLが間違っているか古い、インターネット接続が遅いか制限されている、ウイルス対策ソフトがファイルをロックしている、中途半端に終わった古いダウンロードが残っている、古いパッケージの残骸がディスクに残っている、のいずれかです。

このガイドでは、まずクリーンインストールをステップごとに行い、そのあと画面に出ているエラーメッセージに合った解決策を探します。制限のある学校や職場のネットワーク向けのオフラインインストール、Arduino CLIで詳細な出力を得る方法、2.x系と3.x系のコアの選び方も取り上げます。最後に、小さなテスト用スケッチでインストールが本当にうまくいったかを確認します。

ESP32 DevKit開発ボード
ESP32 DevKit:Arduino IDEでプログラムするには、まずEspressifのボードパッケージをインストールする必要があります。

ESP32のボードパッケージとは何か、なぜこんなに大きいのか

Arduino IDEは、インストールした直後の状態ではArduino純正のボードしか知りません。ESP32を使うには、Espressifが提供するarduino-esp32パッケージ(コア)が必要です。これは数個のファイルどころではなく、XtensaとRISC-Vのコンパイラーツールチェーン、ESP-IDFのライブラリ、書き込みツールのesptool、ファイルシステム用のツールまで含んでいます。現行の3.x系はダウンロードだけで数百メガバイトあり、展開すると数ギガバイトを占めます。ダウンロードが大きいほど途中で切れる可能性も高くなり、エラーの大半はそこから生まれます。

クリーンインストールの手順

  1. 最新のArduino IDE 2.xを使います。1.8.xの古いJava環境では、一部のサーバーに安全な接続を張れないことがあります。
  2. 「ファイル」>「基本設定」を開きます(macOSでは「Arduino IDE」>「設定」)。
  3. 追加のボードマネージャのURLの欄に、次のアドレスを貼り付けます:https://espressif.github.io/arduino-esp32/package_esp32_index.json。すでにほかのURLが入っている場合は、1行に1つずつ書きます。
  4. 「OK」をクリックし、ウィンドウの下部でIDEがパッケージインデックスをダウンロードし終えるのを待ちます。
  5. 左のサイドバーからボードマネージャを開き、esp32と入力して、esp32 by Espressif Systemsの「インストール」をクリックします。Arduino純正の「Arduino ESP32 Boards」パッケージはNano ESP32専用なので、混同しないでください。
  6. 完了したら、「ツール」>「ボード」でESP32 Dev Moduleか、お使いのボードのモデルを選びます。
古い解説記事に載っているhttps://dl.espressif.com/dl/package_esp32_index.jsonというアドレスは、もう更新されておらず、かなり古いバージョンしか載っていません。まだ一覧に残っているなら削除してください。ESP32のURLが2種類同時にあるとバージョンの一覧が混ざり、ダウンロードが失敗する原因になります。

エラーメッセージ別の解決表

インストールに失敗すると、IDE下部の「出力」パネルに長いメッセージが表示されます。全部を読み解く必要はありません。下の表からキーになる語句を探し、その横の解決策を試してください。複数当てはまる場合は、たいてい最後の行が本当の原因です。

メッセージに含まれる語句意味解決策
Error downloading ... package_esp32_index.jsonパッケージインデックスに到達できないURLを1文字ずつ確認し、ブラウザーで開いてみる。開けなければ、原因はネットワークかプロキシ
context deadline exceeded、Client.Timeout exceeded、またはDEADLINE_EXCEEDEDダウンロードが制限時間に達したタイムアウトを延ばし、有線接続かスマートフォンのテザリングを試す
TLS handshake timeout、またはx509: certificate signed by unknown authority安全な接続を確立できなかったパソコンの日付と時刻を直す。社内ネットワークではプロキシ設定を入力する
checksum mismatch、archive hash differs、またはCRC doesn't matchダウンロードしたファイルが壊れているか不完全stagingフォルダにあるESP32のファイルを削除し、インストールし直す
Access is denied、moving extracted archive、またはrenameウイルス対策ソフトか別のプログラムがファイルをロックしたArduino15フォルダをウイルス対策ソフトの除外対象に追加し、IDEを再起動する
no space left on deviceディスクがいっぱいディスクを5 GB以上空け、古いバージョンのコアを削除する
403 Forbidden、または404 Not Found(github.com)GitHubがブロックされているか、アドレスが古い別のネットワークを試し、IDEとURLを最新にする
ボードマネージャにesp32が表示されないURLが入っていない、またはインデックスが更新されていないURLを追加し、IDEを再起動する

タイムアウトと遅い回線

いちばん多いのは、大きなツールチェーンのファイルをダウンロードしている最中に接続が切れるケースです。Arduino IDE 2.xは内部でArduino CLIを使っていて、そのネットワークタイムアウトの初期値は遅い回線には短すぎることがあります。まずは簡単な対策から試しましょう。Wi-Fiの代わりに有線接続やスマートフォンのテザリングを使う、VPNをオフにする(またはオンにする)、回線がすいている時間帯にやり直す、といった方法です。インストールが途中で止まっても、IDEは再開時にダウンロード済みのファイルを取り直さないので、何度か繰り返すうちに最後まで進むこともあります。

それでも直らなければ、タイムアウトを延ばします。IDEを閉じた状態で、ユーザーフォルダにある.arduinoIDE/arduino-cli.yamlをテキストエディターで開き、network:セクションを追加して、その下にインデントを付けてconnection_timeout: 600sという行を書きます。これで待ち時間が10分に延びます。この設定はArduino CLI 1.xを同梱した現行のIDEで有効なので、IDEが古い場合は先にアップデートしてください。社内ネットワークでは、IDEの「基本設定」>「ネットワーク」に必要なプロキシのアドレスを入力します。

ウイルス対策ソフト、ファイアウォール、プロキシ

Windowsで、インストールが終わり近くで「Access is denied」や「moving extracted archive」と出て止まる場合、原因はたいていウイルス対策ソフトです。パッケージを展開すると数千個の小さなファイルができます。Windows Defenderなどのセキュリティソフトがそれらをスキャンしようとしてロックするため、IDEがファイルを所定の場所へ移動できなくなるのです。対策は、インストールの間だけArduino15フォルダをウイルス対策ソフトの除外対象に加えることです。保護を完全にオフにするより、このフォルダだけを除外するほうが安全です。学校や会社のネットワークでは、ファイアウォールがGitHubのダウンロードサーバーをブロックしていることもあります。パッケージインデックスはブラウザーで開けるのにインストールは失敗するという場合は、ネットワーク管理者にプロキシのアドレスを聞くか、自宅でパッケージをインストールして、後述のオフラインの方法で持ち込んでください。

OSArduino15フォルダ途中までのダウンロード(staging)
Windows%LOCALAPPDATA%\Arduino15%LOCALAPPDATA%\Arduino15\staging\packages
macOS~/Library/Arduino15~/Library/Arduino15/staging/packages
Linux~/.arduino15~/.arduino15/staging/packages

古いパッケージの残骸を掃除する

以前に別の方法(たとえばGitHubから手動)でESP32を入れたことがあったり、何年も前に古いバージョンを追加していたりすると、新しいインストールが古いファイルとぶつかることがあります。よくある症状は、インストールはエラーなく終わるのにボード一覧にESP32が2つ出てくる、コンパイル時に「multiple libraries were found」という警告が出る、IDEが古いバージョンを使い続ける、といったものです。次の手順で、完全にまっさらな状態からやり直せます。

  1. Arduino IDEを完全に終了します。
  2. Arduino15の中にあるpackages/esp32フォルダとpackage_esp32_index.jsonファイルを削除します。
  3. staging/packagesにあるESP32関連の途中までのファイル(esp32-、xtensa-、riscv32-、esptoolで始まるもの)を削除します。
  4. スケッチブックのフォルダ(通常はDocuments/Arduino)にhardware/espressifフォルダがあれば、それも削除します。昔の手動インストールの名残で、ボードマネージャからのインストールとぶつかります。
  5. IDEを開き、「基本設定」に現行のESP32のURLだけが残っていることを確認して、パッケージをインストールし直します。
たいていは、ボードマネージャでesp32パッケージの「削除」を1回クリックし、もう一度インストールするだけで直ります。フォルダを手で削除するのは、それで解決しないときだけにしてください。先にバックアップを取っておきたい場合は、Arduino15の中のpackagesフォルダをコピーしておけば十分です。

オフラインインストールと手動インストール

インターネットが制限された学校の実習室や、回線がとても遅い環境では、回線のよいパソコンでパッケージをインストールしてからコピーして持ち込むのがいちばん確実です。この方法は、同じOSのパソコンどうしなら問題なく使えます。コンパイラーはOSごとに別物だからで、WindowsでインストールしたパッケージはmacOSでは動きません。

  1. 回線のよいパソコンに、通常の手順でArduino IDEとESP32パッケージをインストールします。
  2. そのパソコンのArduino15フォルダから、packages/esp32フォルダとpackage_esp32_index.jsonファイルをUSBメモリにコピーします。
  3. 移行先のパソコンでArduino IDEを一度起動して終了し、Arduino15フォルダを作らせます。
  4. コピーしたものを移行先のパソコンのArduino15フォルダの同じ場所に貼り付け、「基本設定」に同じESP32のURLを追加します。
  5. IDEを開きます。ボードマネージャではesp32がインストール済みと表示され、「ツール」>「ボード」にESP32のボードが並びます。

2つ目の方法は、IDEがうまく落とせないファイルをブラウザーでダウンロードし、staging/packagesフォルダに置くことです。IDEはインストールの前にこのフォルダを確認し、ファイル名とチェックサムがパッケージインデックス(package_esp32_index.json)と完全に一致していれば、ダウンロードを省いてそのファイルを直接展開します。どのファイルが必要かは、「出力」パネルの「Downloading」の行でわかります。開発者向けの3つ目の方法は、GitHubのリポジトリをスケッチブック内のhardware/espressifにクローンすることですが、この方法はボードマネージャからのインストールと併用してはいけません。

Arduino CLIで詳細を見ながらインストールする

IDEが表示するのは短いエラーメッセージだけです。どのファイルのどの段階で失敗しているのかを正確に知りたいなら、同じ作業をArduino CLIでコマンドラインから実行できます。IDE 2.xは裏側でこのツールをすでに使っているので、データフォルダが同じであれば、CLIでインストールしたパッケージはIDEにも表示されます。

コマンド役割
arduino-cli config init設定ファイルを作成する
arduino-cli config add board_manager.additional_urls https://espressif.github.io/arduino-esp32/package_esp32_index.jsonESP32パッケージのURLを追加する
arduino-cli core update-indexパッケージインデックスをダウンロードする
arduino-cli core install esp32:esp32 -v詳細な出力付きでESP32パッケージをインストールする
arduino-cli core install esp32:[email protected]特定のバージョンをインストールする
arduino-cli core listインストール済みのコアとそのバージョンを一覧表示する

コアのバージョンを正しく選ぶ

ボードマネージャは常に最新バージョンを勧めてきますが、最新がどのプロジェクトにも合うとは限りません。arduino-esp32はバージョン3.0でESP-IDF 5に移行し、いくつかの関数が変わりました。PWMはledcSetupとledcAttachPinの代わりにledcAttachを使い、タイマーはtimerBegin(0, 80, true)の代わりにtimerBegin(frequency)を使います。2.x系向けに書かれた古いライブラリや解説記事のコードが3.x系でコンパイルできないことがあるのは、そのためです。ボードマネージャでは、パッケージの下にあるドロップダウンから好きなバージョンを選んでインストールできます。同時にインストールしておけるのは1つのバージョンだけです。

バージョンベースのESP-IDF対応チップ選ぶ場面
1.0.63.3ESP32のみかなり古いプロジェクトをそのままビルドし直すときだけ
2.0.174.4ESP32, S2, S3, C33.x系にまだ対応していないライブラリや、古い解説記事
3.x(現行)5.xESP32、S2、S3、C3、C6、H2、およびそれ以降新しいプロジェクトと新しいチップの標準

自分のコードを両方のバージョンでビルドできるようにしたいなら、バージョンマクロを使います。下の例はオンボードLEDをフェードさせるもので、ESP_ARDUINO_VERSION_MAJORが3以上なら新しいPWM関数を、そうでなければ古い関数をコンパイルします。同じ手はタイマーやタッチピンのコードにも使えます。

C++ (Arduino IDE)
1// Hem 2.x hem 3.x çekirdekte derlenen PWM örneği / PWM example that builds on both 2.x and 3.x cores
2const int LED_PIN  = 2;
3const int PWM_FREQ = 5000;     // 5 kHz
4const int PWM_RES  = 8;        // 8 bit: 0-255
5
6void setup() {
7#if ESP_ARDUINO_VERSION_MAJOR >= 3
8  ledcAttach(LED_PIN, PWM_FREQ, PWM_RES);   // 3.x: pin tabanlı API / pin-based API
9#else
10  ledcSetup(0, PWM_FREQ, PWM_RES);          // 2.x: önce kanal kurulur / set up the channel first
11  ledcAttachPin(LED_PIN, 0);
12#endif
13}
14
15void loop() {
16  for (int duty = 0; duty <= 255; duty++) {
17#if ESP_ARDUINO_VERSION_MAJOR >= 3
18    ledcWrite(LED_PIN, duty);               // 3.x: pin numarası / pin number
19#else
20    ledcWrite(0, duty);                     // 2.x: kanal numarası / channel number
21#endif
22    delay(5);
23  }
24}

インストールをテストする

インストールが終わったからといって、すべてうまくいったと決めつけないでください。下のスケッチを書き込み、シリアルモニタを115200ボーで開きます。インストールされているコアのバージョン、ESP-IDFのバージョン、チップのモデル、フラッシュのサイズが表示され、オンボードLEDが点滅します。コンパイル中にエラーが出るなら、原因はまだインストールにあります。書き込みが「Failed to connect」で終わるなら、原因はボードかケーブルかドライバーに移っています。

C++ (Arduino IDE)
1// ESP32 kart paketi kurulum testi / ESP32 board package install test
2// Seri Monitör: 115200 baud / Serial Monitor: 115200 baud
3
4const int LED_PIN = 2;      // çoğu DevKit'te dahili LED / onboard LED on most DevKits
5
6void setup() {
7  Serial.begin(115200);
8  delay(1000);
9  Serial.printf("Arduino-ESP32 core: %d.%d.%d\n",
10                ESP_ARDUINO_VERSION_MAJOR, ESP_ARDUINO_VERSION_MINOR, ESP_ARDUINO_VERSION_PATCH);
11  Serial.printf("ESP-IDF: %s\n", ESP.getSdkVersion());
12  Serial.printf("Yonga / Chip: %s rev %d, %d cekirdek / cores\n",
13                ESP.getChipModel(), ESP.getChipRevision(), ESP.getChipCores());
14  Serial.printf("Flash: %u MB, CPU: %u MHz\n",
15                (unsigned)(ESP.getFlashChipSize() / (1024 * 1024)), (unsigned)ESP.getCpuFreqMHz());
16  pinMode(LED_PIN, OUTPUT);
17}
18
19void loop() {
20  digitalWrite(LED_PIN, !digitalRead(LED_PIN));   // LED yanıp söner / LED blinks
21  delay(500);
22}
ポートの一覧にESP32がまったく出てこない場合、足りないのはボードパッケージではなくUSBドライバーです。CH340ドライバのインストールのガイドをご覧ください。コードはコンパイルできるのに書き込みが「Failed to connect」で終わる場合は、ESP32 Failed to ConnectのガイドにあるBOOTボタンの方法で解決します。

それでもインストールできないときの最終チェックリスト

  • 日付と時刻は合っていますか?時計がずれていると安全な接続の証明書が無効と判断され、ダウンロードがすべて失敗します。
  • ユーザー名に日本語やアクセント付きの文字、空白が含まれていませんか?一部のツールは、アクセント付きの文字やラテン文字以外の文字を含むパスで失敗します。arduino-cli.yamlのdirectories.dataの設定で、パッケージのフォルダをC:\Arduino15のような短いパスに移せます。
  • Windowsの長いパスの制限:260文字を超えるパスがあると、パッケージを展開できないことがあります。Windowsで長いパスのサポートを有効にするか、フォルダのパスを短く保つと解決します。
  • ディスクの空き容量:インストール中は、ダウンロードしたアーカイブと展開後のファイルがしばらく両方とも残ります。少なくとも5 GBの空きを確保してください。
  • 別のツールを試す:IDEでだめならArduino CLIを、それでもだめならPlatformIOを試してください。PlatformIOは独自のサーバーからパッケージをダウンロードします。
  • 待っている間にコードをテストする:インストールの問題が片付くまでは、Wokwiシミュレーターを使ってブラウザー上で回路とコードを動かせます。

ESP32のボードパッケージさえ正しく入れば、Wi-Fi、Bluetooth、センサーのプロジェクトへは数分で進めます。ESP32が初めてなら、まずESP32とは?から読んでみてください。そのあとBlueGraysアプリで、ESP32のLED、オンボードLED、Wi-Fi接続のプロジェクトを、配線図とそのまま使えるコード付きでステップごとに試せます。

よくある質問

ESP32のボードパッケージがインストールできないのはなぜですか?

よくある原因は、ボードマネージャのURLが間違っているか古い、回線が遅くてタイムアウトする、ウイルス対策ソフトがファイルをロックしている、中途半端に終わった古いダウンロードが残っている、のいずれかです。まずURLが https://espressif.github.io/arduino-esp32/package_esp32_index.json になっているかを確認し、そのうえで「出力」パネルのエラーメッセージに合った解決策を試してください。

ESP32の正しいボードマネージャURLは何ですか?

現行の安定版で使うURLは https://espressif.github.io/arduino-esp32/package_esp32_index.json です。古いdl.espressif.comのアドレスにはかなり古いバージョンしか載っていません。まだ一覧に残っているなら削除してください。ESP32のURLが2つ同時にあると不具合の原因になります。

Arduino IDEの「Error downloading」はどう直しますか?

まずパッケージのURLをブラウザーで開いてみてください。開けなければ、原因はネットワーク、プロキシ、ファイアウォールのいずれかです。開ける場合は、stagingフォルダにある途中までのファイルを削除し、パソコンの時計を確認して、有線接続かスマートフォンのテザリングでインストールをやり直します。

ESP32のコアは2.xと3.xのどちらを入れるべきですか?

新しいプロジェクトや、ESP32-C6のような新しいチップには3.x系を選びます。頼りにしているライブラリや解説記事が2.x系向けに書かれていて3.x系でコンパイルできない場合は、2.x系の最終リリースである2.0.17をインストールしてください。バージョンはボードマネージャのドロップダウンからいつでも切り替えられます。

インターネットなしでESP32パッケージをインストールできますか?

できます。同じOSでインターネットにつながるパソコンにパッケージをインストールし、そのArduino15フォルダからpackages/esp32フォルダとpackage_esp32_index.jsonファイルを、移行先のパソコンの同じ場所にコピーします。IDEを開くと、パッケージがインストール済みとして表示されます。

ESP32パッケージにはどのくらいのディスク容量が必要ですか?

バージョンによって異なりますが、現行の3.x系はツールチェーンとライブラリを合わせて数ギガバイトを占めます。インストール中はアーカイブと展開後のファイルが両方とも残るので、少なくとも5 GBの空きを確保しておけば安心です。

全プロジェクトを見る
ESP32の内蔵LEDを点滅
ES-4初級

ESP32の内蔵LEDを点滅

ESP32 DevKit V1に内蔵された青色LEDを点滅させます。外付け部品は不要です!ESP32を購入したら、最初に試すプロジェクトです。GPIO 2が内蔵LEDにつながっています。

4.8(29)
54
ESP32でLEDを点滅
ES-1初級

ESP32でLEDを点滅

ESP32のGPIO出力の基本を学びます。デジタルピンからLEDを点灯・消灯させて、点滅させます。Arduino UNOの定番のLED点滅プロジェクトのESP32版です。Arduino環境で使う基本的な点滅コマンドは同じですが、ESP32のピン配置と3.3 VのGPIO電圧レベルはArduino UNOとは異なります。

4.7(37)
108
ESP32でボタンによるLED制御(押している間だけ点灯)
ES-2初級

ESP32でボタンによるLED制御(押している間だけ点灯)

ボタンを押している間はLEDが点灯し、離すと消灯します。ESP32のデジタル入力ピンと内蔵プルアップ抵抗の使い方を学びます。INPUT_PULLUPモードを使うため、外付け抵抗は不要です。

4.6(36)
57
ESP32の信号機
ES-5初級

ESP32の信号機

赤・黄・緑の3個のLEDで、実際の信号機を再現します。赤は長く、黄は短く、緑は長く点灯させ、実際の信号機に近いタイミングで動かします。GPIOを順番に制御する基本例です。

4.4(22)
45
ESP32とLDRモジュールで光の強さを読み取る
ES-11初級

ESP32とLDRモジュールで光の強さを読み取る

LDRモジュールの生のADC値と、暗い状態・明るい状態の基準値から計算した相対的な明るさの割合を、シリアルモニタでリアルタイムに確認します。この割合はルクスの測定値ではありません。モジュールの校正の仕組みを学べます。しきい値の決定に使うため、プロジェクト10の前に取り組むのが適しています。

4.6(36)
55
ESP32のPWMでLEDをフェード
ES-8初級

ESP32のPWMでLEDをフェード

LEDの明るさを0から最大へ、最大から0へと滑らかに変化させます。Arduinoと同じようにanalogWrite()でPWMを制御します。ESP32 Arduino Core 3.0+では同じ構文がそのまま使えます。ピンの定義とpinMode、analogWriteだけで実現できます。

4.8(36)
55
ESP32 Wi-Fi STA接続(LCDディスプレイ付き)
ES-25上級

ESP32 Wi-Fi STA接続(LCDディスプレイ付き)

このプロジェクトでは、ESP32をステーション(STA)モードで家庭のWi-Fiネットワークに接続し、安全で障害に強い接続を実現します。SSIDとパスワードを別のsecrets.hファイルに保存してGitへの流出を防ぎ、自動再接続の仕組みを実装します。RSSIによる信号強度とIPアドレスはI2C LCDディスプレイに表示します。内蔵LEDは状態表示に使います。実運用を想定した接続管理の仕組みです。

4.4(21)
38
ESP32非同期Webサーバー(LCDにIPアドレスを表示)
ES-27上級

ESP32非同期Webサーバー(LCDにIPアドレスを表示)

このプロジェクトでは、ESP32を同じWi-Fiネットワーク上のスマートフォンやパソコンから操作できる非同期Webサーバーにします。ESPAsyncWebServerライブラリを使うと、従来のWebServer.hのように1つのリクエストで処理がブロックされず、複数のリクエストを同時に処理できます。ブラウザーでESP32のIPアドレスを開き、ON/OFFボタン(/onと/offのルート)を押すと、GPIO 5に接続したLEDを点灯・消灯できます。

4.8(16)
26