Zenn
🐧

WSL 2: Debianのインストールと初期設定ガイド (2025年版)

2025/03/11に公開

tl;dr

Windows Terminal 上で、以下のコマンドを実行して、Debian をインストール・セットアップします。

  1. WSLの既定のバージョンを 2 に設定

    wsl --set-default-version 2
    
  2. Debianをインストール

    wsl --install -d Debian
    
  3. ユーザーアカウントを作成

    wsl -d Debian
    
  4. Windows Terminalを再起動

以上で、Windows TerminalDebian のプロファイルが自動追加され、メニューから選択して起動できます。

Enjoy!

はじめに

atsushifx です。
この記事では、WSL 2環境に Debian をインストールし、Linux コマンドラインを快適に利用する方法を解説します。
また、インストール時のトラブルシューティングについても紹介します。

WSL 2を利用すると、Windows上でコンテナ開発や Linux ネイティブな開発環境を構築できます。

用語集

  • WSL 1 (Windows Subsystem for Linux 1):
    Linux システムコールを Windows システムコールへ変換する方法で、NTFS ファイルシステム上で Linux のバイナリを実
    行する技術

  • WSL 2 (Windows Subsystem for Linux 2):
    Windows上で Linux環境を実現するための仮想化技術

  • Debian:
    安定性とセキュリティを重視した Linuxディストリビューション

  • Windows Terminal:
    Windows 向けの複数のシェル環境に対応した、モダンなターミナルエミュレータ

  • PowerShell:
    Windows上で利用されるコマンドラインシェルおよびスクリプト環境

  • GUID:
    Windows 内部でオブジェクトを一意に識別する識別子

  • dism.exe:
    Windows のシステムイメージを管理するコマンドラインツール

  • BIOS / UEFI:
    PC の起動を管理するファームウェア (BIOSはレガシー形式、UEFIはその後継規格で、より高度な機能を提供)

1. 前提条件

WSLを使用するには、以下の条件が必要です。

  1. 仮想化支援機能の有効化:
    (Intel VT-x または AMD-V)がBIOS/UEFIの設定で有効になっていること。

  2. Windowsのバージョン:
    Windows 11 を推奨。
    Windows 10 では一部の機能に制限あり (wsl -updateが使用できない)

  3. WSL および Virtual Machine Platform の有効化:
    WSL, Virtual Machine PlatformおよびHyper-Vの各機能が Windows上で有効になっていること。
    (通常、"Virtualization Technology" というオプション名で記載される)

上記の設定については、GitHub からパッケージをダウンロードして WSL をセットアップする方法 を参考にしてください。

そのほか、インストール操作で、

  1. Windows Terminal

  2. PowerShell (Windows PowerShell ではなく)

を使用しています。

2. WSL 2とは

2.1 WSL 2 の概要

WSL 2は、Microsoft がカスタマイズした Linuxカーネルを使用し、仮想環境を作成します。
WSL 2は、WSL 1と異なり、完全な Linux カーネルを利用し、ファイルシステムのパフォーマンスが向上しています。そのため、開発用途に適した環境を提供します。

2.2 WSL 2 を選ぶ理由

WSL 2は、Linuxカーネルをネイティブに使用し、WSL 1よりも高速で高い互換性を提供します。
特に、Docker などのコンテナ技術や最新の Linux ツールの利用に適しています。
また、Windows のファイルシステムと統合され、エディタや IDE との連携も容易です。

3. Debianのインストール、セットアップ

WSL 2Debianをインストールする手順を解説します。
Windows Terminal上でコマンドを実行して、Debianをインストールします。

3.1 Windows Terminalの起動

以下の手順で、Windows Terminalを起動します。

  1. 実行ダイアログの表示:
    [Win]+Rキーで[ファイル名を指定して実行]ダイアログを開きます。
    ファイル名を指定して実行
    ファイル名を指定して実行

  2. ターミナルの起動:
    ダイアログにwtと入力して、[Enter]キーを押します。
    Windows Terminalが起動します。
    ターミナル
    ターミナル

3.2 インストール先をWSL 2にする

DebianWSL 2環境にインストールするため、WSLの既定バージョンをWSL 2に設定します。
以下の手順で、WSL 2に設定します。

  1. 既定のバージョンを設定する:

    wsl --set-default-version 2
    
  2. メッセージが表示される:

    WSL 2 との主な違いについては、https://aka.ms/wsl2
     を参照してください
     この操作を正しく終了しました。
    
    

以上で、インストール先をWSL 2に設定できました。

現在の WSL のバージョン (既定のバージョン) を、次の手順で確認できます。

  1. 既定のバージョンを確認する:

    wsl --status
    
  2. メッセージが表示される:

    既定のバージョン: 2
    

上記のように、既定のバージョンが 2 であれば、WSL 2にインストールされます。

3.3 Debianのインストール手順

以下の手順で、WSL 2Debianをインストールします。

  1. Debianをインストールする:
    以下のコマンドを実行し、Debianをインストールします。

    wsl --install -d Debian
    
  2. メッセージの出力:
    以下のメッセージがターミナルに表示されます。

    ダウンロード中: Debian GNU/Linux
    [==========================47.2%                           ]
    
    インストール中: Debian GNU/Linux
    [==========================47.2%                           ]
    
    ディストリビューションが正常にインストールされました。'wsl.exe -d Debian' を使用して起動できます
    

上記のメッセージが表示されれば、インストールは完了です。

3.4 ユーザーアカウントの作成

Debian上でファイル操作やソフトウェア管理をするため、UNIXユーザーアカウントを作成する必要があります。
以下の手順で、ユーザーアカウントを作成します。

  1. Debianの起動:
    以下のコマンドで、Debianを起動します。

    wsl -d Debian
    
  2. ユーザーアカウントの作成:
    Debianをはじめて起動した場合は、次のようなメッセージが表示されます。
    画面の指示に従ってください。

    Please create a default UNIX user account. The username does not need to match your Windows username.
    For more information visit: <https://aka.ms/wslusers>
    Enter new UNIX username:
    

    ユーザー名を入力します。

    Enter new UNIX username: <myUserAccount>
    
  3. パスワードの設定:
    続けて、パスワードを入力するプロンプトが表示されます。

    ユーザー名を設定するプロンプトが表示されます。
    パスワードを入力して、ユーザーアカウントを作成します。

    New password:
    Retype new password:
    

以上で、ユーザーアカウントの作成は終了です。

4. Windows Terminalの設定

4.1 プロファイルにDebianを追加する

Debianのインストールに成功すると、Windows TerminalのプロファイルにDebianが追加されます。
Windows Terminalを再起動すると、以下のようにメニューにDebianが表示されます。
シェルメニュー
シェル

5. トラブルシューティング

5.1 代表的なトラブルと対処法

[WSL-001]: WSL 2に切り替えられない (WSL 2 required)

  • コマンド:
    wsl --set-default-version 2

  • エラーメッセージ:
    "WSL 2 requires an update to its kernel component. For information please visit https://aka.ms/wsl2kernel"

  • 日本語訳:
    WSL 2 のカーネルコンポーネントが古いため、更新が必要です。詳細は https://aka.ms/wsl2kernel を参照してください。

  • 原因:
    WSL 2のカーネルが古い

  • 対処法:
    WSL のカーネルを最新のバージョンに更新し、PC を再起動

    wsl --update
    shutdown /r /t 0
    

[WSL-002]: WSL 2に切り替えられない (Please enable the Virtual Machine)

  • コマンド:
    wsl --set-default-version 2
  • エラーメッセージ:
    "Please enable the Virtual Machine Platform Windows feature and ensure that virtualization is
    enabled in the BIOS."
  • 日本語訳:
    Virtual Machine Platform 機能、およびBIOSの仮想化支援機能が有効になっていることを確認してください
  • 原因:
    • WindowsVirtual Machine Platform機能が無効化されている
    • BIOSまたはUEFIで仮想化支援機能 (Intel VT-x または AMD-V) が無効になっている
  • 対処法:
    • PowerShellを管理者権限で開いて、以下のコマンドを実行後、PC を再起動:

      dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
      shutdown /r /t 0
      
    • BIOS設定で、仮想化支援機能(Intel VT-x または、AMD-V) を有効化

[WSL-003]: WSLDebian がインストールできない

  • コマンド:
    wsl --install -d Debian
  • エラーメッセージ:
    "There is no distribution with the supplied name."
  • 日本語訳:
    指定した名前のディストリビューションが存在しません。
  • 原因:
    インストールしようとしたディストリビューションが存在しない、またはみつからない
  • 対処法:
    • wsl --list --online:
      インストール可能なディストリビューションを確認する
    • Microsoft Store:
      Microsoft Storeから対象のLinux ディストリビューションをインストール

[WSL-004]: WSL 2に切り替わらない (WSL default version)

  • コマンド:
    wsl --status
  • エラーメッセージ:
    "WSL default version remains as WSL 1"
  • 日本語訳:
    WSLの既定のバージョンが、 1 のままです。
  • 原因:
    wsl --set-default-version 2が正しく適用されていない
    (WSL を完全に終了していない可能性がある)
  • 対処法:
    • PowerShellを管理者権限で開き、次のコマンドを実行後、WSLを再起動

      wsl --set-default-version 2
      wsl --shutdown
      

[TERM-001]: Windows Terminalの[プロファイル]にDebianが存在しない

  • コマンド:
    Windows Terminalのシェルメニュー
  • エラー:
    シェルにDebianが表示されていない
  • 原因:
    プロファイルにDebianの項目がない
  • 対処法:
    • Windows TerminalのプロファイルにDebianを追加する:
      1. settings.jsonを開く:
        [設定]-[JSON ファイルを開く]で、Windows Terminalの設定ファイルをエディタで開く。

      2. Debianプロファイルを追加:
        settings.json内のprofilesセクションにあるlist配列に Debian の項目を追加します。

        "profiles":
        {
           "list":
           [
           ]
        }
        

        下記、Debianの項目を追加。

        {
          "guid": "{<GUID>}",
          "hidden": false,
          "name": "Debian",
          "source": "Microsoft.WSL"
        }
        
      3. Windows Terminalを再起動

おわりに

以上で、Windows上に Debian がインストールできました。
これにより、AWSやその他のクラウドサービスに近い Linux環境を Windows上で構築できるようになり、開発環境の幅が大きく広がります。
Linuxツールが利用できるという大きな利点により、各種開発やテストがよりスムーズになります。

今後は、Debian のカスタマイズ方法や具体的な開発環境の構築手順について解説する予定です。
まずは、使いやすいDebian環境の構築に挑戦してみてください。

それでは、Happy Hacking!

参考資料

Webサイト

GitHubで編集を提案

Discussion

ログインするとコメントできます