在 Windows 上安装 WSL 完全指南（含离线安装包｜直链下载）

WSL 3.0.3 更新内容

WSL 3.0.3 于 2026 年 10 月 9 日发布，本版多为内部修复：

• 内核组件更新：Microsoft.WSL.Kernel 更新到 6.18.54.1。
• WSL 容器（wslc）改进：支持从标准输入读取镜像构建上下文；改进事件过滤器，支持按事件类型匹配容器与网络过滤器；拒绝带多余参数的命令。
• 修复与稳定性：修复新建发行版时误报 wsl.conf 警告；binfmt 挂载改为可写；修复 LifetimeManager 竞态等稳定性问题。

本次更新不改变下文安装 WSL 和 Linux 分发版的基本流程。

WSL Containers 的主要能力

WSLc 已正式可用。它提供 Windows 上的 Linux 容器运行与管理能力，不是把分发版的运行架构从 WSL 2 改成“WSL 3”。

能做什么

• 命令行运行容器：通过随 WSL 提供的 wslc.exe 构建、运行和管理 Linux 容器，也可使用内置别名 container.exe。例如运行 Web 服务、容器化开发环境或本地 AI 工作负载。
• 在 Windows 应用中调用容器：开发者可通过 WSL Containers API 拉取镜像、启动容器，并处理输入输出、目录挂载、端口映射及 GPU 访问。相关 SDK 使用 Microsoft.WSL.Containers NuGet 包；普通命令行用户不需要额外安装该 SDK。
• 接入开发与企业管理工具：已有 VS Code Dev Containers、Container Tools 和 Aspire 等集成。企业可通过 Intune 控制是否允许使用 WSLc、限制可拉取镜像的仓库，并通过 Microsoft Defender for Endpoint 的 WSL 插件查看容器进程、文件和网络活动。

从命令行开始使用

在已安装 WSL 的 Windows 终端或 PowerShell 中更新，并检查软件包版本：

wsl --update
wsl --version

离线环境可使用本文提供的 WSL 3.0.3 MSI 包覆盖安装，但这不代表下面的容器镜像也已下载。首次运行此示例时，如果本地没有 ubuntu:latest，WSLc 会从 Docker Hub 拉取镜像，需要能访问该仓库及其镜像下载服务，DNS 解析和 HTTPS 连接也必须正常：

wslc run --rm -it ubuntu:latest bash -c "echo Hello world from WSL container!"

示例启动 Ubuntu 容器，输出一行文字后通过 --rm 自动删除该容器。这里要求的是能访问 Docker Hub 镜像仓库，不是要求先安装 Docker Desktop。

WSLc 可以使用 Docker Hub 等 Docker 镜像源，在构建、运行和管理 Linux 容器方面替代 Docker 的部分功能。

镜像拉取失败

拉取镜像时，如果出现以下网络错误，应尝试修复与 Docker Hub 或所用镜像源的网络连接后重试：

Get "https://registry-1.docker.io/v2/": dial tcp: lookup registry-1.docker.io on [fec0:0:0:ffff::3]:53: dial udp [fec0:0:0:ffff::3]:53: connect: network is unreachable

正式版的常用能力

表中列的是命令入口，操作具体容器时还需要指定容器名称等参数。

存储和网络有哪些变化

• 按用户管理会话：会话由以调用用户身份运行的 wslcsession.exe 进程管理，执行容器创建、挂载和端口绑定等操作，减少这些操作对特权服务的依赖。
• 独立存储与目录挂载：每个会话有自己的 VHD，用于保存镜像、容器和网络等状态；支持 Windows 目录挂载，也支持以 VHD 为后端的卷，提供原生 Linux 文件系统。需要在删除容器后保留的数据应放在卷中。
• Windows 文件访问：WSLc 使用 virtiofs 共享 Windows 目录。微软介绍其相较 Plan 9 方案约有两倍性能，但这针对目录访问路径，不代表普通 WSL 分发版或所有任务都提速两倍。
• 新的 Consommé 网络模式：通过用户身份运行的 Windows 进程处理 DNS、TCP/UDP 路由和端口映射，让容器流量接入 Windows 网络栈，改善与 VPN、防火墙的兼容性。

使用边界

只需要 Ubuntu 命令行或常规 Linux 开发环境时，仍可按下文安装分发版，不必使用 WSLc。WSLc 也不意味着现有 Docker、Compose 工作流都可以直接迁移：截至 3.0.3 正式发布，Compose 支持仍在开发计划中，不能将 compose up 当作已经可用的功能。WSL Containers API 的 C++/WinRT 接口也仍处于预览阶段。

一、WSL 是什么

适用于 Linux 的 Windows 子系统（WSL）允许在 Windows 上运行 Linux 环境，主要用途包括：

• 安装 Ubuntu、Debian 等 Linux 分发版。
• 运行 Linux 命令行、开发工具和服务。
• 运行 Linux 图形应用及 GPU 计算任务，相关功能需要系统和驱动支持。

开源资源

• WSL 开源文档网站：https://wsl.dev
• GitHub 上的 WSL 仓库：https://github.com/microsoft/WSL
• WSL 发布页（MSI 离线包从这里下载）：https://github.com/microsoft/WSL/releases

二、安装前需要了解的 WSL 2

• 默认架构：通过 wsl --install 新安装的分发版默认使用 WSL 2，在后台的轻量虚拟机中运行 Linux 内核。
• 虚拟化要求：WSL 2 需要启用硬件虚拟化和 Windows「虚拟机平台」组件。
• 文件存放：开发项目优先放在 Linux 文件系统中，并使用 Linux 环境中的工具处理，减少跨 Windows 与 Linux 文件系统读写。

WSL 软件包 3.x 与 WSL 2 架构的区别见第 3.5 节。需要比较两种架构时，可阅读微软的 WSL 1 与 WSL 2 对比文档。

三、WSL 的在线安装

3.1 先决条件

要使用下面的命令，系统必须是 Windows 10 版本 2004（内部版本 19041）或更高版本，或者 Windows 11。版本更老的机器，请参考「手动安装页」。

查看系统版本可按 Windows 徽标键 + R，输入 winver 后回车。

3.2 一条命令完成安装

现在只需要一条命令，就能装好运行 WSL 所需的全部组件。右键点击 PowerShell，选择「以管理员身份运行」，输入 wsl --install，装完重启计算机即可：

wsl --install

这条命令会启用 WSL 所需的全部功能，并装上 Ubuntu 这个 Linux 分发版。

第一次启动新装好的分发版时会弹出控制台窗口，需要等一会儿让文件解压缩并写入本机。之后再启动就快了，基本不到一秒。

注意
只有在完全没装过 WSL 的机器上，这条命令才会走安装流程。如果运行 wsl --install 后只是弹出 WSL 帮助文本，可以先运行 wsl --list --online 看看有哪些分发版可用，再用 wsl --install -d <DistroName> 安装。如果安装进度卡在 0.0%，先运行 wsl --install --web-download -d <DistroName> 把分发版下载下来，然后再执行安装。

3.3 更改安装的默认 Linux 分发版

默认装的是 Ubuntu。想换一个，加 -d 参数就行：

# 安装指定的分发版
wsl.exe --install -d [Distro]

# 查看可从在线商店获取的分发版列表
wsl.exe --list --online

把 [Distro] 换成你想装的分发版名称。

如果想装的分发版不在可安装列表里，可以用 TAR 文件「导入任意 Linux 分发版」；某些情况下也可以用 .appx 文件安装。你还可以「构建自己的自定义 Linux 分发版」给 WSL 用。

3.4 设置 Linux 用户信息

装好 WSL 之后，还要为新装的分发版创建用户账户和密码。详见「设置 WSL 开发环境的最佳实践」。

3.5 检查 WSL 软件包版本与分发版架构

WSL 3.0.3 是软件包版本号，WSL 1 和 WSL 2 则表示 Linux 分发版使用的运行架构，两者不是同一类版本。安装 WSL 3.0.3 后，分发版仍可使用 WSL 2；设置默认架构时仍使用 wsl --set-default-version 2，不能将参数改成 3。

# 查看 WSL 软件包及内核、WSLg 等组件版本
wsl.exe --version

# 列出已安装的分发版、运行状态及运行架构（WSL 1 或 WSL 2）
wsl.exe --list --verbose

# 为以后新建的分发版设置默认运行架构（WSL 2）
wsl.exe --set-default-version 2

# 设置 wsl 命令默认使用哪个分发版
wsl.exe --set-default <Distro>

# 临时运行某个分发版，不改变默认设置
wsl.exe --distribution <DistroName>

例如，在 PowerShell 里输入 wsl -s Debian，就把默认分发版设成了 Debian。此后在 PowerShell 中运行 wsl npm init，就相当于在 Debian 里执行 npm init。

3.6 启动与退出分发版

# 启动默认分发版
wsl

# 启动指定分发版
wsl -d Ubuntu

在 Linux 命令行中输入 exit 退出。也可以从开始菜单或 Windows 终端启动已安装的分发版。

四、WSL 基本命令参考

下面按 PowerShell / Windows 命令提示符的格式列出 WSL 常用命令。如果要在 Bash 或分发版的命令行里执行这些命令，需要把 wsl 写成 wsl.exe。完整列表请运行 wsl --help。

4.1 命令速查表

4.2 安装相关的选项

wsl --install 的常用选项：

• --distribution：指定要安装的 Linux 分发版。有哪些可选，运行 wsl --list --online 就能查到。
• --no-launch：只安装，装完不自动启动。
• --web-download：从网络源安装，不走 Microsoft Store。
• --location：指定分发版装到哪个文件夹。

机器上还没装 WSL 时可用的选项：

• --inbox：用 Windows 自带组件安装 WSL，而不是从 Microsoft 应用商店安装。（此后 WSL 更新随 Windows 更新推送，而不是由商店随时推送。）
• --no-distribution：只装 WSL，不装任何分发版。

注意
在 Windows 10 或更早版本上，可能需要在 --install 里显式加上 -d 指定分发版：wsl --install -d <distribution name>

4.3 已安装 WSL 的升级方法

已有 WSL 环境时，可在 PowerShell 中更新 WSL 本体：

# 在线更新 WSL
wsl --update

# Microsoft 应用商店不可达时，从 GitHub 获取更新
wsl --update --web-download

# 检查更新后的软件包版本
wsl --version

上面的两条更新命令选择一种执行即可。离线环境使用与设备架构对应的新版 MSI 包覆盖安装，步骤见第五节。

升级 WSL 本体不需要卸载或重新安装 Ubuntu 等分发版，也不应执行 wsl --unregister；该命令会永久删除指定分发版及其数据。Linux 分发版内部的软件包更新由其包管理器单独完成。

五、WSL 的离线安装

本节面向这几类情况：访问不了 Microsoft 应用商店、处在内网环境、或者 wsl --install 一直卡在 0.0% 。全部材料都可以提前下载到 U 盘或内网文件服务器上分发。

官方流程见脱机安装文档。分发版 .wsl 文件的官方地址可在 DistributionInfo.json 中查找。

5.1 离线安装前的准备

建议把这些文件放在一个短路径目录里（例如 C:\wsl-offline\ 或 D:\wsl-offline\），避免路径中的空格和中文引起命令解析问题。

5.2 步骤一：启用「虚拟机平台」可选组件

以管理员身份打开 PowerShell，执行：

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

等价的 PowerShell 写法：

Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -NoRestart

也可以走图形界面：控制面板 → 程序 → 程序和功能 → 启用或关闭 Windows 功能，勾选「虚拟机平台」，确定后重启。

注意
这一步做完必须重启计算机才会生效。没重启就装分发版，很可能报 0x80370102 之类的错。

5.3 步骤二：安装 WSL MSI 离线包

以下以 x64 安装包为例。双击 wsl.3.0.3.0.x64.msi 按向导安装；也可以在管理员 PowerShell 里静默安装：

msiexec /i "C:\wsl-offline\wsl.3.0.3.0.x64.msi" /quiet /norestart

装完之后重启（如果上一步还没重启过），然后验证：

wsl --version
wsl --status

wsl --version 会输出 WSL 软件包版本、内核版本、WSLg 版本等信息（使用本节安装包时，WSL 软件包版本应为 3.0.3.0）；wsl --status 则显示默认分发类型、默认分发版和内核版本等概况。

注意
离线环境下不要用 wsl --update 或 wsl --update --web-download，这两个都要联网（前者走 Microsoft 应用商店，后者走 GitHub）。以后要升级，重新下载新版 MSI 包覆盖安装即可。

5.4 步骤三：使用 .wsl 文件离线安装分发版

最省事的做法是直接双击那个 .wsl 文件 —— Windows 已经把这种格式和 WSL 关联好了，会自动调用 WSL 完成安装，全程不联网。两个 Ubuntu 版本二选一，装一个就够；装出来的分发版名称由文件本身决定。

如果想自己指定分发版名称或安装位置，再改用命令行：在管理员 PowerShell 里用 --from-file 指向本地的 .wsl 分发包（路径按实际存放位置改）。

# 安装 Ubuntu 26.04
wsl --install --from-file "C:\wsl-offline\Ubuntu-26.04.wsl"

# 或者装 Ubuntu 24.04.4
wsl --install --from-file "C:\wsl-offline\Ubuntu-24.04.4.wsl"

可用的选项以 wsl --install --help 的输出为准。

5.5 步骤四：初始化用户并验证

第一次启动新装的分发版时会弹出控制台窗口，需要等文件解压缩并写入磁盘；随后会要求创建用户账户和密码。之后每次启动就基本是秒开了。

# 查看已装的分发版、运行状态与 WSL 版本
wsl --list --verbose

# 启动默认分发版
wsl

进到分发版里，可以再确认一下系统版本：

cat /etc/os-release
uname -a

六、离线安装包下载指南

• 请访问下载页面：

  • WSL v3.0.3：https://www.changjiu365.cn/download/WSL
  • Ubuntu 26.04：https://www.changjiu365.cn/download/wsl-ubuntu/26.04
  • Ubuntu 24.04.4：https://www.changjiu365.cn/download/wsl-ubuntu/24.04.4

• 页面内可选的下载源包括：

  • 本站高速直链： 享受由阿里云 CDN 带来的高速、稳定下载。
  • 公共云盘镜像： 本站提供 百度网盘、阿里云盘、123云盘、天翼云盘、迅雷云盘、Google Drive 与 OneDrive 分流。

• 重要信息：

  • 版本选择： WSL 安装最新版本即可；两个 Ubuntu 版本二选一，不用都下。
  • 文件校验： 下载完成后，请务必用页面提供的 SHA-256 哈希值核对文件一致性。

七、常见问题与排错

八、参考资料

• 安装 WSL | Microsoft Learn
• 什么是适用于 Linux 的 Windows 子系统 | Microsoft Learn
• 比较 WSL 版本 | Microsoft Learn
• WSL 的基本命令 | Microsoft Learn
• 适用于旧版本的 WSL 手动安装步骤
• 设置 WSL 开发环境的最佳实践
• WSL 常见问题解答
• GitHub 上的 WSL 发布页
• WSL 3.0.3 发布说明
• WSL Containers 正式发布公告
• WSLc 架构介绍
• WSL Containers 使用指南

‍