開発環境ガイド
Claude Code 公式ドキュメント ↗手順を始める

困ったとき

困ったときは

環境構築でつまずきやすい点と、確認する順番をまとめます。

つまずいたときは、まず 「どこで実行したか」 を確認します。Windows側(PowerShell)とWSL(Ubuntu)を取り違えると、多くのエラーが起きます。入力行が PS C:\...> なら Windows側、名前@PC名:~$ なら WSL側です。

切り分けの手順

  1. エラーメッセージを、最後まで読む(原因が書かれていることが多いです)
  2. 実行した場所(Windows側かWSL側か)が合っているか確認する
  3. ターミナルを 開き直して、もう一度実行する
  4. このページで、同じ症状を探す
  5. エラーメッセージをそのまま検索する、または Claude Code に見せて相談する

エラーメッセージは、画面に表示されたまま コピーして 相談すると、原因を特定しやすくなります。

WSL

インストールが0.0%のまま進まない

ダウンロードを先に行ってから、インストールします。PowerShell(管理者)で実行します。

wsl --install --web-download -d Ubuntu

仮想化に関するエラーが出る

WSL 2は、パソコンの仮想化機能を使います。エラーに「仮想化」や「Virtualization」と出る場合は、パソコンの BIOS/UEFI設定で、仮想化機能(Intel VT-x、AMD-Vなど)を有効 にします。設定画面の開き方はパソコンによって違うため、メーカーの案内を確認してください。

wsl --install が使えない

Windows 10では、バージョン2004(ビルド19041)以降が必要です。winver で確認し、Windows Updateで更新します。

Ubuntuのウィンドウが開かない

スタートメニューで「Ubuntu」を検索して、起動します。それでも開かないときは、PowerShellで wsl.exe --list --verbose を実行し、Ubuntuが一覧にあるか確認します。

動きがおかしいので、WSLを再起動したい

PowerShellで次を実行してから、Ubuntuを開き直します。

wsl --shutdown

ファイルの読み書きが遅い

プロジェクトが、Windows側のフォルダ(/mnt/c/...)にある可能性があります。~/projects など、WSL側のフォルダ に移します。

VS Code

code: command not found

UbuntuからVS Codeを起動できない状態です。次を順に試します。

  1. Ubuntuのターミナルを開き直す
  2. Windows側で、VS Codeが入っているか確認する
  3. VS Codeを入れ直し、インストーラーの「PATHへの追加」にチェックを入れる

左下に「WSL: Ubuntu」と表示されない

コマンドパレット(F1)で WSL: Reopen Folder in WSL を実行します。

拡張機能が動かない

WSLにつないだ状態では、拡張機能をWSL側にも入れる必要があるものがあります。拡張機能の画面で、「WSL: Ubuntu にインストール」のボタンが出ていれば押します。Claude Code の拡張機能が表示されないときは、コマンドパレットで Developer: Reload Window を実行します。

Git / GitHub

Permission denied (publickey)

SSHキーがGitHubに登録されていない、または違う鍵が使われています。

  1. cat ~/.ssh/id_ed25519.pub の内容が、GitHubのSSHキー設定に登録されているか確認する
  2. ssh -T git@github.com を実行して、もう一度確認する

大量のファイルが「変更された」と表示される

WindowsとLinuxの改行コードの違いが原因のことがあります。プロジェクトを WSL側にだけ置く と、起きにくくなります。Windows側と共有する場合は、.gitattributes に次を書きます。

* text=auto eol=lf

Author identity unknown と表示されてコミットできない

名前とメールアドレスが未設定です。「Gitをセットアップする」のページの手順で設定します。

git config --global user.name "あなたの名前"
git config --global user.email "you@example.com"

push が拒否された

GitHub側に、手元にない変更がある可能性があります。git pull で取り込んでから、もう一度 git push します。

Python(uv)

uv: command not found

インストール直後は、まだ uv が見つからないことがあります。次のコマンドを実行するか、ターミナルを開き直します。

source $HOME/.local/bin/env
uv --version

uv run pytest で、pytestが見つからない

pytestは、自分で追加する必要があります。

uv add --dev pytest

テストで ModuleNotFoundError と表示される

from py_sample import add のように、src の下のフォルダ名で読み込んでいるか確認します。プロジェクト名のハイフン(-)は、アンダースコア(_)になります。また、uv run pytest で実行しているか確認します(pytest だけだと、仮想環境の外で動くことがあります)。

VS Codeが、別のPythonを使っている

F1 キーでコマンドパレットを開き、Python: Select Interpreter で、プロジェクトの .venv を選びます。

Claude Code

claude: command not found

次を順に試します。

  1. Ubuntuの中 で実行しているか確認する(PowerShellではありません)
  2. ターミナルを開き直す
  3. それでも直らなければ、コマンドの置き場所を、PATHに追加する
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
claude --version

インストールのコマンドが失敗する

syntax error near unexpected token '<' や 403 などと表示される場合があります。公式の「インストールのトラブルシューティング」で、エラーに合う対処を探してください。

PowerShellで The token '&&' is not a valid statement separator と出た場合は、コマンドプロンプト向けのコマンドをPowerShellで実行しています。WSLでは、Ubuntuで curl ... | bash のコマンドを使います。

ログインできない

  1. claude を起動して、/login と入力し、ログインし直す
  2. ブラウザが開かない場合は、表示されたURLをコピーして、Windowsのブラウザに貼り付ける
  3. 契約しているプランが、Claude Code に対応しているか確認する(無料プランは対象外です)

状態を調べたい

claude doctor

インストールの状態、設定のエラー、対処の提案が表示されます。

動きがおかしくなった・会話が長くなりすぎた

/clear で会話をリセットします。それでも変なら、claude を終了して、起動し直します。

それでも解決しないとき

Esc で閉じます