はじめに (対象読者・この記事でわかること)

本記事は、Flutter を初めて導入しようとしている開発初心者や、既に環境構築を試みたものの「flutter not found」というエラーで立ち往生している方を対象としています。
この記事を読むことで、Flutter SDK の公式サイトからのダウンロード手順、環境変数 PATH の正しい設定方法、コマンドラインからの動作確認手順、さらにエラー時の具体的なトラブルシューティング手順が理解でき、実際に flutter --version が正常に動作する状態まで導くことができるようになります。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。

  • 基本的なコマンドライン操作（Windows の PowerShell、macOS / Linux のターミナル）
  • Git のインストールと簡単な使用法（Flutter の依存取得で利用します）

Flutter 環境構築の概要と「flutter not found」エラーの背景

Flutter は Google が提供するクロスプラットフォーム UI フレームワークで、モバイル・デスクトップ・Web のアプリを単一コードベースで開発できます。公式が配布する Flutter SDK をローカルに展開し、flutter コマンドをシステムの PATH に登録することで、どのディレクトリからでも Flutter CLI を利用できるようになります。

しかし、インストール後に「flutter not found」と表示されるケースは意外と多く、主に以下の原因が考えられます。

  1. PATH への登録が不完全
    SDK の bin ディレクトリがシステム環境変数に正しく追加されていないと、シェルが flutter コマンドを認識できません。

  2. インストール場所の選択ミス
    Windows ではデフォルトで C:\src\flutter が推奨されますが、スペースや日本語を含むパスに展開すると内部スクリプトが失敗することがあります。

  3. シェルの再起動不足
    環境変数を変更した後にターミナルや PowerShell を再起動しないと、変更が反映されず flutter が見つからない状態が続きます。

  4. 依存ツールの不足
    macOS/Linux では git がインストールされていないと SDK のクローンが失敗し、結果として実行ファイルが欠損します。

  5. SDK の破損や不完全ダウンロード
    ネットワーク障害などで zip ファイルが壊れた場合、flutter 実行ファイルが欠如し「not found」エラーが発生します。

本稿では、これらの原因を踏まえたうえで、実際に「flutter not found」エラーを解消するための具体的な手順を順を追って解説します。

Flutter 環境構築の具体的手順とエラー対策

ステップ 1: Flutter SDK のダウンロードと展開

  1. 公式ダウンロードページへアクセス
    - URL: https://flutter.dev/docs/get-started/install
    それぞれの OS（Windows, macOS, Linux）に合わせた zip ファイルを取得します。

  2. 適切なディレクトリへ展開
    - Windows: C:\src\flutter（管理者権限が不要な場所）
    - macOS/Linux: $HOME/development/flutter など、ユーザーのホームディレクトリ配下が安全です。
    注意点として、パスにスペースや日本語文字列を含めないことが重要です。

  3. 展開後のディレクトリ構造確認
    flutter/ ├─ bin/ │ ├─ flutter │ └─ cache/ └─ packages/ bin/flutter が実行可能ファイルです。

ステップ 2: PATH 環境変数への登録

Windows の場合

  1. システム環境変数編集画面を開く
    - 「このPC」 > 右クリック > 「プロパティ」 > 「システムの詳細設定」 > 「環境変数」

  2. ユーザー変数 or システム変数の Path に以下を追加
    C:\src\flutter\bin 追加後、「OK」をクリックして全ウィンドウを閉じます。

  3. PowerShell で確認
    powershell $Env:Path -split ';' | Where-Object { $_ -match 'flutter' } 期待通りにパスが表示されれば成功です。

macOS / Linux の場合

  1. シェル設定ファイルに追記（使用シェルに応じて）
    - Bash (~/.bashrc または ~/.bash_profile)
    - Zsh (~/.zshrc)

  2. PATH 追加コマンド例
    sh export PATH="$HOME/development/flutter/bin:$PATH"

  3. 設定を反映
    sh source ~/.bashrc # または source ~/.zshrc

  4. 確認
    sh which flutter # => /home/username/development/flutter/bin/flutter が表示されれば OK

ステップ 3: 必要な依存ツールのインストール

  • Git
  • Windows: https://git-scm.com/download/win からインストーラ実行
  • macOS: brew install git

  • Linux: sudo apt-get install git などディストリビューションに合わせる

  • Android Studio（Android 開発向け）

  • 必要に応じてインストールし、SDK Manager で Android SDK と Command-line Tools を取得

  • Xcode（iOS 開発向け、macOS のみ）

  • App Store からインストールし、Xcode のコマンドラインツールを有効化
    sh sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

ステップ 4: Flutter のセットアップコマンド実行

Sh

flutter doctor
  • flutter doctor はインストール状態、依存ツール、ライセンス同意状況を総合的にチェックします。
  • 画面に表示される [✓] が全て揃っていれば基本的な環境構築は完了です。
  • 未解決項目があれば、指示通りにツールをインストールしたり、ライセンスに同意したりします。

典型的なエラーメッセージと対処例

エラー 内容 解決策
flutter: command not found PATH に flutter/bin が未登録、またはターミナルが再起動されていない PATH を再確認し、シェルを再読み込み (source ~/.bashrc など)
Unable to locate git Git がインストールされていない、または PATH に含まれない Git をインストールし、git --version が出ることを確認
Android SDK not found Android Studio が未インストール、または SDK パスが未設定 Android Studio をインストールし、flutter config --android-sdk <sdk_path> で手動設定
License not accepted Android SDK ライセンスが未承諾 flutter doctor --android-licenses を実行し、全てのライセンスに同意

ハマった点やエラー解決

1. PowerShell の実行ポリシーが原因

  • 症状: flutter コマンド入力で The term 'flutter' is not recognized と表示。PATH は正しく設定しているはずなのに動作しない。
  • 原因: PowerShell の実行ポリシーが Restricted で、外部スクリプトの実行がブロックされていた。
  • 解決策: 管理者権限で PowerShell を開き、以下を実行。 powershell Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned その後ターミナルを再起動すると flutter doctor が正常に動作。

2. macOS の zsh で PATH が二重に設定されていた

  • 症状: flutter コマンドは見つかるが、flutter doctor が Unable to locate Android SDK と出続ける。
  • 原因: ~/.zshrc と ~/.zprofile の両方に同じ export PATH=... 行があり、結果的に PATH が過剰に長くなり Android SDK の探索パスが切り捨てられた。
  • 解決策: ~/.zprofile の重複行を削除し、source ~/.zshrc で再読込。echo $PATH で期待通りの順序になっていることを確認。

3. Windows の「ユーザーアカウント制御（UAC）」が原因で SDK の書き込み権限が不足

  • 症状: flutter upgrade 実行時に Permission denied エラーが多数出る。
  • 原因: C:\src\flutter ディレクトリを管理者権限で作成したが、通常ユーザーでの書き込み権限が付与されていない。
  • 解決策: エクスプローラでディレクトリを右クリック → 「プロパティ」→「セキュリティ」→「編集」し、対象ユーザーに「フルコントロール」権限を付与。再度 flutter upgrade を実行すると成功。

まとめ

本記事では、Flutter SDK の正しいダウンロード・配置手順から環境変数 PATH の設定、必要な依存ツールの導入、flutter doctor による検証方法、そして「flutter not found」エラーが頻出する典型的シナリオとその具体的対処法までを体系的に解説しました。

  • PATH への正しい登録が最重要
  • Git・Android SDK・Xcode などの依存ツールが欠如するとエラーになる
  • シェルやターミナルの再起動、実行ポリシーの確認を忘れない

これらを踏まえて環境構築を行えば、開発初期段階でつまずくことなく、すぐに Flutter アプリの作成に着手できるはずです。次回は、実際にプロジェクトを作成し、エミュレータ／実機でのデバッグ方法を扱う予定です。

参考資料