WSL 用のカスタム Linux ディストリビューションを構築する

2025-06-10

このガイドでは、WSL ディストリビューション ( .wsl ファイル) を作成して配布する手順について説明します。

WSL ディストリビューションには、次の 2 つの部分があります。

ルートファイルシステム (tar ファイルとして配布)
マニフェストエントリ (ディストリビューションメタデータを含む)

このガイドは、 WSL リリース 2.4.4 以降にのみ適用されます。

注

前 appx ベースのディストリビューションパッケージの手順についてはこのリポジトリを参照してください。

WSL ルートファイルシステム tar ファイルとは何ですか?

WSL ディストリビューションは、Windows 上の .wsl ファイル拡張子を持つ tar ファイルによって定義されます。

TAR ファイル (テープアーカイブの略) は、配布やバックアップを容易にするために複数のファイルを 1 つのファイルにまとめるために使用されるアーカイブファイルの一種です。 TAR ファイルには、Linux ディストリビューション (すべてのディストリビューションファイル) のルートファイルシステムと WSL 構成ファイルが含まれています。 WSL 構成ファイルは、WIndows オペレーティングシステムにディストリビューションをインストールして起動する方法を指示します。

WSL ディストリビューションにしたい Linux システムが完成したら、次の手順に従って作業を開始します。

WSL 構成ファイルを作成する

ディストリビューションに含める必要がある構成ファイルは 2 つあります。

/etc/wsl-distribution.conf: WSL を使用して初めて起動したときに Linux ディストリビューションを構成する方法を制御するディストリビューション保守管理者によって作成されたファイル。
/etc/wsl.conf: ユーザーに固有のグローバルシステム設定を含み、ディストリビューションの起動方法を制御するファイル。 WSL 構成ファイルの詳細については、こちらを参照。

WSL 配布構成ファイルを追加する

ディストリビューション構成ファイル /etc/wsl-distribution.confは、ユーザーが初めて起動したときに Linux ディストリビューションを構成する方法を定義します。このファイルは、対話形式でユーザーアカウントを作成したり、使用許諾契約書を表示したりするために使用できます。

/etc/wsl-distribution.conf ファイルのサンプルを次に示します。

# /etc/wsl-distribution.conf

[oobe]
command = /etc/oobe.sh
defaultUid = 1000
defaultName = my-distro

[shortcut]
enabled = true
icon = /usr/lib/wsl/my-icon.ico

[windowsterminal]
enabled = true
ProfileTemplate = /usr/lib/wsl/terminal-profile.json

WSL 配布ファイルの構成オプション:

鍵	価値	デフォルト	注
`oobe.command`	ひも	`<none>`	OOBE は、すぐに使用するエクスペリエンスの略です。このコマンドは、ユーザーがディストリビューションで対話型シェルを初めて開くと実行されます。そのコマンドが 0 以外を返した場合、失敗したと見なされ、ユーザーはシェルを開くことができません。
`oobe.defaultUid`	整数 (integer)	`<none>`	ディストリビューションが開始する既定の UID。これは、 `oobe.command` スクリプトで新しいユーザーを作成するときに便利です。
`oobe.defaultName`	ひも	`<none>`	ディストリビューションが登録されている既定の名前。この既定の名前は、次のコマンドに置き換えることができます。 `wsl.exe --install <distro> --name <name>`
`shortcut.icon`	ひも	既定の WSL アイコン	配布のスタートメニューショートカットのアイコン。最大サイズが a0/& `.ico` の形式である必要があります `10MB`
`shortcut.enabled`	ブーリアン	ほんとう	ディストリビューションのインストール時にスタートメニューのショートカットを作成するかどうかを指定します。
`windowsterminal.profileTemplate`	ひも	`<none>`	このディストリビューションのWindows ターミナルプロファイルを生成する JSON テンプレート。
`windowsterminal.enabled`	ブーリアン	ほんとう	ディストリビューションのインストール時にターミナルプロファイルを作成する必要があるかどうか。 `profileTemplate`が設定されていない場合は、既定のプロファイルが生成されます。
`windowsterminal.profileTemplate`	ひも	ターミナルテンプレートファイルへのパス	このディストリビューションのWindows ターミナルプロファイルを生成する JSON テンプレート。

ディストリビューションの最初の実行エクスペリエンス (OOBE) を作成する必要があります。使用できる Bash スクリプトの例を次に示します。このスクリプトでは、 oobe.defaultUid が 1000 に設定されていることを前提としています。

#!/bin/bash

set -ue

DEFAULT_GROUPS='adm,cdrom,sudo,dip,plugdev'
DEFAULT_UID='1000'

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

if getent passwd "$DEFAULT_UID" > /dev/null ; then
  echo 'User account already exists, skipping creation'
  exit 0
fi

while true; do

  # Prompt from the username
  read -p 'Enter new UNIX username: ' username

  # Create the user
  if /usr/sbin/adduser --uid "$DEFAULT_UID" --quiet --gecos ''  "$username"; then

    if /usr/sbin/usermod "$username" -aG "$DEFAULT_GROUPS"; then
      break
    else
      /usr/sbin/deluser "$username"
    fi
  fi
done

Windows ターミナルプロファイルを生成する

WSL では、ディストリビューションのインストール時にWindows ターミナルプロファイルが自動的に生成されます。ディストリビューションメンテナーは、WSL 構成ファイル ( windowsterminal.profileTemplate) で/etc/wsl-distribution.confを設定することによって生成される生成されたプロファイルをカスタマイズできます。

json ファイルはターミナルプロファイルの json 形式に従います。プロファイルの例を次に示します。


{
  "profiles": [
    {
      "antialiasingMode": "aliased",
      "fontWeight": "bold",
      "colorScheme": "Postmodern Tango Light"
    }
  ],
  "schemes": [
    {
      "name": "Postmodern Tango Light",
      "black": "#0C0C0C",
      "red": "#C50F1F",
      "green": "#13A10E",
      "yellow": "#C19C00",
      "blue": "#0037DA",
      "purple": "#881798",
      "cyan": "#3A96DD",
      "white": "#CCCCCC",
      "brightBlack": "#767676",
      "brightRed": "#E74856",
      "brightGreen": "#16C60C",
      "brightYellow": "#F9F1A5",
      "brightBlue": "#3B78FF",
      "brightPurple": "#B4009E",
      "brightCyan": "#61D6D6",
      "brightWhite": "#F2F2F2"
    }
  ]
}

このファイルでは、プロファイルの nameや commandLineを指定する必要はありません。これらは、端末プロファイルの生成時に WSL によって自動的に追加されます。

配布ごとにローカル設定の WSL 構成を追加する

ディストリビューションルートファイルシステムのコンテキストでは、配布ごとに/etc/wsl.confローカル設定で systemd が既定で開始されるかどうかなど、systemd 設定を構成することをお勧めします。次の例を見てください。

# /etc/wsl.conf

[boot]
systemd=true|false

配布作成者は、 boot.systemd 値を true (有効) または false (有効ではない) に設定することで、systemd が既定で有効になっているかどうかを判断します。

既定で systemd を有効にすることを選択した場合は、Systemd の推奨事項を参照してください。

でサポートされているすべての設定については/etc/wsl.confAdvanced 設定の構成を参照してください。

tar ファイルを作成する

配布ファイルと構成ファイルが配置されると、ルートファイルシステムを tar ファイルにキャプチャできます。

tar ファイルを作成する推奨される方法は次のとおりです。

$ cd /path/to/rootfs
$ tar --numeric-owner --absolute-names -c  * | gzip --best > ../install.tar.gz

tar のルートはファイルシステムのルートである必要があります (ルートファイルシステムを含むディレクトリではありません)。

推奨される圧縮形式は gzip です。他の圧縮形式では、古い WSL バージョンとの互換性が損なうリスクがあります。

構成に含める必要があり、含めてはならないファイルの一覧については、「構成ファイルの推奨事項」を参照してください。

既存の Linux ディストリビューションの tar ファイルを取得するには、「 WsL で使用する Linux ディストリビューションをインポートする」で Docker コンテナーをエクスポートする方法に関するガイダンスを参照してください。

tar ファイルアーカイブの準備ができたら、「ローカルで配布をテストしてローカルで試す」を参照してください。

wsl ファイル拡張子を作成する

最後の手順では、カスタム Linux ディストリビューションを表す tar ファイルを作成したら、名前を変更して .tar ファイル拡張子を .wsl ファイル拡張子に変更します。このファイル拡張子の名前を変更すると、WSL ディストリビューションとしてマークされます。 tar の名前を .tar から .wsl に変更すると、エクスプローラーで開くと (ダブルクリックして) Windows にファイルが正しくインストールされます。このダブルクリックエクスペリエンスを正常に機能させるには、oobe.defaultName ファイルに/etc/wsl-distribution.confエントリが必要です。

WSL ディストリビューションを配布する

WSL ユーザーは、 wsl --list --online を実行して使用可能なディストリビューションを表示し、 wsl --install <distroName> で直接インストールできます ( <distroName> を Linux ディストリビューションの実際の名前に置き換えます)。このプロセスは、配布マニフェストファイルによって制御されます。このマニフェストファイルを顧客の Linux ディストリビューションに追加して、 wsl --install コマンドオプションに含めることができます。

.wslファイル拡張子を使用して作成および名前を変更したカスタム Linux ディストリビューション tar は、必要に応じて配布できます。ダウンロードしたユーザーは、コマンドラインから wsl --install --from-file <fileLocation> で直接インストールできます ( <fileLocation> をファイルの実際の場所に置き換えます)。または、カスタム WSL ディストリビューションの .wsl ファイルをダブルクリックして開くことができます。

ディストリビューションマニフェストの詳細

配布マニフェストには、wsl --install <distribution>経由でインストールできるディストリビューションに関するメタデータが含まれています。

tar ベースの Linux ディストリビューションは、次の形式で ModernDistributionの下に一覧表示されます。

"ModernDistributions": {

"<flavor>": [
    
    {
    "Name": "<version name>",
    "FriendlyName": "<friendly name>",
    "Default": true | false,
    "Amd64Url": {
        "Url": "<tar url>",
        "Sha256": "<tar sha265 hash>"
        },
    "Arm64Url": {
        "Url": "<tar url>",
        "Sha256": "<tar sha265 hash>"
        }
    }
}

各 flavor エントリには、インストール可能なディストリビューションの一覧が含まれています。ディストリビューションは、フレーバー名 (既定のエントリがインストールされている場合) またはバージョン名を使用してインストールできます。

コマンド wsl --install 次のマニフェストで動作する方法を確認します。

{
    "ModernDistributions": {
        "my-distro": [
            {
                "Name": "my-distro-v3", 
                "Default": true,
                "FriendlyName": "My distribution version 3 (latest)"
                 [...]
            },
            {
                "Name": "my-distro-v2", 
                "Default": false,
                "FriendlyName": "My distribution version 2"
                 [...]
            }
    }        
}

サンプルインストールコマンド:

$ wsl --install my-distro # Installs 'my-distro-v3' since it's the default for 'my-distro' flavor
$ wsl --install my-distro-v3 # Installs 'my-distro-v3' explicitly
$ wsl --install my-distro-v2 # Installs 'my-distro-v2' explicitly

すべての WSL ユーザーの `wsl --install` にディストリビューションを追加する

WSL ディストリビューションをすべてのユーザーが使用できるようにするには、 WSL GitHub リポジトリでプル要求を開き、配布情報を含むように DistributionInfo.json ファイルを変更します。

このプル要求は、WSL チームによってレビューされます。

企業またはビジネスグループの `wsl --install` にディストリビューションを追加する

また、選択した Windows デバイスのレジストリキーを編集して、 wsl --install で選択したグループにのみ配布を使用できるようにすることもできます。

WSL 分散マニフェストは、 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxssでレジストリ値を作成することでオーバーライドできます。

DistributionListUrl: ディストリビューションマニフェストの URL をオーバーライドします。
DistributionListUrlAppend: そのマニフェスト URL からインストール可能なディストリビューションの一覧にディストリビューションを追加します

どちらのレジストリ値も文字列 (REG_SZ) であり、URL 形式である必要があります。

WSL リリース 2.4.4 以降では、ローカルテストを容易にするために、 file:// プロトコルがサポートされています。想定される形式は、 file:///C:/path/to/fileです。

配布をローカルでテストする

ディストリビューション tar をテストするには、次のサンプル PowerShell スクリプトを使用して、ディストリビューションマニフェストを新しいディストリビューションでオーバーライドできます。まず、次のスクリプトを override-manifest.ps1として保存します。

#Requires -RunAsAdministrator

[cmdletbinding(PositionalBinding = $false)]
param (
    [Parameter(Mandatory = $true)][string]$TarPath,
    [string]$Flavor = "test-distro",
    [string]$Version = "test-distro-v1",
    [string]$FriendlyName = "Test distribution version 1")

Set-StrictMode -Version latest

$TarPath = Resolve-Path $TarPath
$hash = (Get-Filehash $TarPath -Algorithm SHA256).Hash


$manifest= @{
    ModernDistributions=@{
        "$Flavor" = @(
            @{
                "Name" = "$Version"
                Default = $true
                FriendlyName = "$FriendlyName"
                Amd64Url = @{
                    Url = "file://$TarPath"
                    Sha256 = "0x$hash"
                }
            })
        }
    }

$manifestFile = "$PSScriptRoot/manifest.json"
$manifest | ConvertTo-Json -Depth 5 | Out-File -encoding ascii $manifestFile


Set-ItemProperty -Path "HKLM:SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss" -Name DistributionListUrl -Value "file://$manifestFile" -Type String -Force

次に、管理者特権の PowerShell で次のコマンドを実行して、ローカルマニフェストを構成します。

.\override-manifest.ps1 -TarPath /path/to/tar

完了すると、 wsl.exe --list --onlineからの次の出力が表示されます。

$ wsl --list --online
The following is a list of valid distributions that can be installed.
Install using 'wsl.exe --install <Distro>'.

NAME              FRIENDLY NAME
test-distro-v1    Test distribution version 1

その後、 wsl.exe --install test-distro-v1 を実行して、新しいディストリビューションのインストールを試すことができます。

完了したら、 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\DistributionListUrl を削除して公式マニフェストに戻すことができます。

WSL カスタム Linux ディストリビューションの推奨事項

構成ファイルの推奨事項

カスタム配布に、 /etc/wsl.conf 構成ファイルと /etc/wsl-distribution.conf 構成ファイルの両方が含まれていることを確認します。両方のファイルは root:root によって所有されている必要があり、それらのアクセス許可は 0644する必要があります。
oobe.command設定を使用して新しいユーザーを作成する場合は、uidとoobe.defaultUidの両方を1000に設定する必要があります。
配布構成ファイルで oobe.defaultName と shortcut.icon の両方を設定してください。 /etc/wsl-distribution.conf
ルートファイルシステムにファイル /etc/resolv.conf を含めないでください。
/etc/passwdにルートユーザーを含めます。このルートユーザーの uid は 0する必要があります。
/etc/shadowにパスワードハッシュは含めてはなりません。
アーカイブにはカーネルまたは initramfs を含めてはなりません。

Systemd の推奨事項

systemd が有効になっている場合は、WSL で問題が発生する可能性があるユニットを無効にするか、マスクする必要があります。以下のユニットは、WSL ディストリビューションで問題を引き起こすことがわかっています (システムユニットとユーザーユニットの両方に適用されます)。

systemd-resolved.service
systemd-networkd.service
NetworkManager.service
systemd-tmpfiles-setup.service
systemd-tmpfiles-clean.service
systemd-tmpfiles-clean.timer
systemd-tmpfiles-setup-dev-early.service
systemd-tmpfiles-setup-dev.service
tmp.mount

次の方法で共有

WSL 用のカスタム Linux ディストリビューションを構築する

WSL ルート ファイルシステム tar ファイルとは何ですか?