Getting Started with Windows Subsystem for Linux on Windows Server

Windows Subsystem for Linux (WSL) brings the convenience of native Linux functionality to Windows Server. You have access to a fully functional Linux kernel in the distribution of your choice embedded right where you have instant access without needing to rely on a heavy virtualization layer or a thick emulator. This article focuses on WSL in Windows Server 2022 as the current version, but includes notes for WSL on Windows Server 2019.

[citationic]

Overall, Microsoft maintains decent documentation on WSL, which you can always access at aka.ms/wsl. However, their directions for installing distributions from APPX on Windows Server have some clarity problems and may not work for you. If you want, you can try them. The steps shown in this article have all been verified functional as of the date of publication/most recent update.

Install WSL Using DISM

You can install WSL on Windows Server using the command-line DISM utility in two ways. The first uses an elevated command line and the dism.exe program. Remember that feature names in DISM are case sensitive. If you are on Windows Server 2019 or you do not wish to use WSLv2 on Windows Server 2022, you can omit the references to VirtualMachinePlatform. Note that because Windows Server 2022 always defaults to version 2 for WSL, attempting to install a distribution without this component will usually result in error code 0x8004032d. The sections in this article on installing distributions show how to set the default version to 1.

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /featurename:VirtualMachinePlatform

You can also use PowerShell:

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux, VirtualMachinePlatform

You can use Install-WindowsFeature or its alias of Add-WindowsFeature, however, it only works for the base WSL package. If you have Windows Server 2022 and want to use WSLv2, then you will still need to add the “VirtualMachinePlatform” package as shown above.

Install-WindowsFeature -Name Microsoft-Windows-Subsystem-Linux

If the method you use does not prompt for reboot, you can initiate one with 

Restart-Computer

. in PowerShell or 

shutdown /r /t 0

 at any prompt. Afterward, you have the WSL infrastructure but no distributions. Skip the next installation section for instructions.

Not Recommended: Install WSL Using Pre-placed Stub

With some caveats, you can sometimes install Windows Subsystem for Linux on Windows Server 2022 the same way that you can on Windows 10 or Windows 11. Just open an elevated command-line and run:

wsl --install --no-distribution

This may not notify you afterward, but it requires a reboot. You can initiate from the command line with 

shutdown /r /t 0

.

When it works, it does so because Windows Server 2022, like the desktop editions of Windows with more recent updates, includes just enough of the Windows Subsystem for Linux to operate the installer. Once this completes, you might have the framework necessary to run Linux distributions. However, it may set the system to default to version 2 but miss a vital component that allows for anything beyond version 1, and it does not include any distributions. Instructions for adding distributions appear after the remaining installation sections. Sometimes, it doesn’t even actually enable the feature! To save time troubleshooting any of these problems, use the DISM steps in the next section.

Not Recommended: Install WSL Using Server Manager

You can also use Server Manager to install the base component of WSL. This will not install the “VirtualMachinePlatform” component, so you can’t use WSLv2. That component does not appear anywhere in the Server Manager UI, so you’ll need to follow the DISM steps. This does not apply on Windows Server 2022 or when you don’t want to use WSLv2 on Windows Server 2022.

From Server Manager’s start page, use the Add Roles and Features link. Step through the wizard to the Features page and check the option for Windows Subsystem for Linux.

Continue through the wizard. If you check the box for automatic restart, then Windows Server will take care of it. Otherwise, you can restart manually at your convenience.

After the restart, proceed to the next section to learn how to add a Linux distribution.

Acquiring Packaged Linux Distributions for WSL

Microsoft provides multiple distributions ready for use with WSL. On a typical desktop installation of Windows, you would install them directly from the Windows Store. Windows Server does not provide access to the Windows Store. Therefore, you’ll need to download distributions and install them manually.

Before downloading anything, decide where you want to house your Linux distributions. You can use something simple, like C:\WSL. Create the directory with default options. You can do this in Windows Explorer or at a command line:

mkdir C:\WSL

You can download from Microsoft’s site. You should not use a production server for general Internet access. Ideally, a server won’t even have an installed Internet browser. Instead, access the site from a desktop installation of Windows and use a secured channel to transfer it to your server environment. Rather than repeat everything from the Microsoft site here, you can just follow this link: https://learn.microsoft.com/en-us/windows/wsl/install-manual#downloading-distributions.

A couple of notes on what you’ll find:

  • Notice that each of the links includes an aka.ms shortcut URL, such as https://aka.ms/wslubuntu for the current Ubuntu distribution.
  • Below the links, you can find examples for using PowerShell and the command-line utility cURL to download.

The site delivers distributions as appx (package application) files, but as mentioned during the intro of this article, those directions may not work. The next section shows how to extract them for use.

Quick, Foolproof WSL Distribution Setup Directions

This section contains the shortest possible directions. If you have already tried to follow the Microsoft instructions and a bunch of Internet solutions and learned a lot but still failed, then you will probably only need this section. It makes a lot of assumptions about your knowledge. If you find these instructions too simplistic, skip past and use the longer versions afterward.

  1. Download the major .appx file for the distribution
  2. If you used a browser, remember to unblock the file (Unblock-File)
  3. Rename the .appx to .zip. If it’s an .appxbundle file, then you’ll still rename to .zip.
  4. Extract the files from that zip
  5. If the extracted files have more appx files for the distribution, the source was probably an appxbundle. Determine which of the contained appx files you want to use for your distribution, rename that to zip, and extract its files.
  6. Optional: Register that appx with Add-AppxPackage (this will not work on any core mode installation and does not work and is not necessary on any edition of Windows Server 2019)
  7. Rename the appx that you just registered to .zip
  8. Extract the files from that zip. You specifically need the distribution executable (e.g., ubuntu.exe) and the install.tar.gz
  9. On Windows Server 2022, you may have instances where you can’t or don’t want to use WSLv2, but WSL wants to run v2 by default. Switch to version 1 with 
    wsl --set-default-version 1
    . If you expected WSLv2 to work, make sure that you installed the “VirtualMachinePlatform” optional feature (discussed in the DISM section near the beginning of the article).
  10. Run the distro’s executable
  11. Delete the extracted files except for the distro executable, the rootfs folder (if present), and the temp folder (if present)

Going forward, you can just run that same executable to start this distribution. You can add its location to the path to initiate it from anywhere. After it has executed once, it will also appear as one of the options in 

wsl --list

 (Windows Server 2022+) or 

wslconfig /l

 (Windows Server 2019).

Quick Walkthrough: Linux Distro Installation for WSL on Windows Server 2019

These steps show the exact process to start an installation of the current Ubuntu distribution in WSL on Windows Server 2019 fresh install, Standard edition, core mode, updated via online Windows Update to available patches on November 24, 2023. They will also work on WS2019 with the desktop experience.

  1. If not already in PowerShell, start PowerShell from an elevated command prompt (
    powershell.exe
    )
  2. Install-WindowsFeature -Name Microsoft-Windows-Subsystem-Linux
  3. cd $env:USERPROFILE
  4. cd .\Downloads
    \
  5. Invoke-WebRequest -UseBasicParsing -OutFile ubuntu_current.zip -Uri https://aka.ms/wslubuntu
  6. Expand-Archive -Path .\ubuntu_current.zip .\ubuntu_current
  7. cd .\ubuntu_current
  8. Rename-Item .\Ubuntu_2204.1.7.0_x64.appx .\Ubuntu_2204.1.7.0.zip
  9. mkdir C:\WSL\Ubuntu
  10. Expand-Archive .\Ubuntu_2204.1.7.0.zip C:\WSL\Ubuntu
  11. cd C:\WSL\Ubuntu
  12. .
    \ubuntu.exe

This will start an install process, then ask you to set up the credentials to use in this distribution.

Because Windows Server 2019 cannot use WSL2, only a subset of the instructions that you find for wsl.exe will work. Use 

wsl --help

 to show what you can use. For the other functions, such as removing a distribution, use wslconfig. 

wslconfig --help

 will show its options. For example, to remove the distribution that you just set up, run 

wslconfig /u Ubuntu

. If you do that, you can immediately run the 

ubuntu.exe

 again to reinstall it, provided that you left the install files intact.

If you want to clean up your directory tree after installation, the C:\WSL\Ubuntu location mentioned in the walkthrough only needs the 

ubuntu.exe

 file, the 

rootfs

folder, and the 

temp

folder. If you delete the temp folder, your next run of the distribution will recreate it. Do not try to remove the rootfs folder as it contains your distribution and has file names that the NTFS tools can’t handle. If you try to remove the folder, it will partially work and complain about something, usually an undeletable aux file. Use 

wslconfig /u

 instead. If you’ve already wrecked it and you can’t remove the folder, try going to an elevated command prompt (not PowerShell) and run the following: 

rd \\.\C:\WSL\Ubuntu\rootfs /s /q

.

Quick Walkthrough: Linux Distro Installation for WSL on Windows Server 2022

These steps show the exact process to start an installation of the current Ubuntu distribution in WSL on a Windows Server 2022 fresh install, Standard edition, core mode, updated via online Windows Update to available patches on November 24, 2023. This follows the pattern of the previous section in which you manually retrieve the appx package from the Microsoft site even though you now have the online option to perform this automatically. We chose this technique because, except for the download part, it will work for servers that do not have an Internet connection.

These steps will also work on WS2022 with the desktop experience.

  1. Start an elevated PowerShell session (powershell.exe)
  2. Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux, VirtualMachinePlatform
  3. If prompted, allow the computer to restart
  4. If you had to restart, return to an elevated PowerShell prompt.
  5. cd $env:USERPROFILE
  6. cd .\Downloads
    \
  7. Invoke-WebRequest -UseBasicParsing -OutFile ubuntu_current.zip -Uri https://aka.ms/wslubuntu
  8. Optional: If running a Desktop Experience installation of Windows Server, see the second note in the next sub-section before proceeding
  9. Expand-Archive -Path .\ubuntu_current.zip .\ubuntu_current
  10. cd .\ubuntu_current
  11. Rename-Item .\Ubuntu_2204.1.7.0_x64.appx .\Ubuntu_2204.1.7.0.zip
  12. mkdir C:\WSL\Ubuntu
  13. Expand-Archive .\Ubuntu_2204.1.7.0.zip C:\WSL\Ubuntu
  14. cd C:\WSL\Ubuntu
  15. If you prefer to use WSL v1 or must because of a hardware limitation, run the following: 
    wsl --set-default-version 1
  16. .
    \ubuntu.exe

This will start an install process, then ask you to set up the credentials to use in this distribution.

If you want to clean up your directory tree after installation, the C:\WSL\Ubuntu location mentioned in the walkthrough only needs the 

ubuntu.exe

 file, the 

rootfs

folder, the fsserver file, and the 

temp

folder. If you delete the temp folder, your next run of the distribution will recreate it. Do not try to manually remove the rootfs folder as it contains your distribution and has file names that the NTFS tools can’t handle. If you try to remove the folder, it will partially work and basically just wreck the whole thing. Use 

wsl --unregister

 instead. If you’ve already wrecked it, try going to an elevated command prompt (not PowerShell) and run the following: 

rd \\.\C:\WSL\Ubuntu\rootfs /s /q

.

Notes for WSL On Windows Server 2022

The above directions used a core mode installation, which varies from the desktop experience in two major ways.

First, the steps will work just fine on the desktop experience, but the core mode lacks several capabilities: No use of 

wsl --install

wsl --update

, or any 

--online

functionality. All these result in a vague 

Class not registered

 message. You also can’t install the most recent WSL recent from the Github page, apparently because of the same anonymous missing component.

Second, on desktop experience, you can use Add-AppxPackage on the internal APPX component before renaming it to ZIP at step 11. Example: 

Add-AppxPackage .\Ubuntu_2204.1.7.0_x64.appx

. If you do this and then follow the rest of the directions, the system creates a folder for the APPX package under your user profile (ex: C:\Users\Administrator\AppData\Local\Packages). The 

rootfs

 and 

temp

 folders for the distribution will appear there. You can then delete everything in the place where you extracted the files (ex: C:\WSL\Ubuntu in the directions above) except for the distribution’s executable (ubuntu.exe in the directions). You can even move the executable anywhere you like.

If you get errors trying to run Add-AppxPackage on the distribution package that mention dependency failure, install the Universal Windows Platform desktop component first. This will only work with the desktop experience, not on core.

Installing an APPX WSL Distribution on Windows Server

Here begin the longer instructions for installing a Linux distribution from APPX on Windows Server. This will show the process more in-depth than the quick directions in the preceding two sections and will use Windows Server 2022 with the desktop experience instead of core.

From this point onward, the directions assume that you have installed WSL, created a location to store your distributions, and have acquired at least one APPX-packaged distribution. These steps will use C:\WSL as the root for WSL distributions, so modify them to match what you decided to use.

Preparing Windows Server 2022 to run Linux Distributions

Before you start, consider two things.

First, WSL on Windows Server 2022 always wants to run version 2 distributions. If you didn’t enable the “VirtualMachinePlatform” or your hardware just doesn’t support it, WSL will refuse to install distributions. You can follow the instructions in DISM section at the beginning of the article to enable the missing component.

Alternatively, you can tell WSL to use version 1. At an elevated command prompt, run:

wsl --set-default-version 1

From this point forward, all Linux distributions will install as version 1. It will not impact existing distributions. You can change the default version and the version of an installed distribution at any time.

Second, update WSL. Unfortunately, this does not work on core installations of Windows Server 2022 or any installation of Windows Server 2019. For offline servers, you can get the bits from Github. For online servers, you can update right from the command prompt.

At an elevated command prompt, run:

wsl --update

This will retrieve and install the most current WSL bits. If it fails because the server can’t access the Internet, WSL will still operate your distribution.

Extracting and Installing the Linux APPX

This example shows an openSUSE distribution instead of Ubuntu to shake things up a bit. It downloads as an APPX file, which the article has talked about all along. The Ubuntu distribution in the preceding sections uses a nested delivery technique. If you download that one using a web browser, you’ll get an “appxbundle” file. You rename an APPXBUNDLE to ZIP just like the APPX example shown here, then open that archive to find nested APPX files. Select the one you want (usually by architecture, ex: x64 or ARM), extract it, and use that APPX as the following example shows.

Screenshot of a downloaded openSUSE-Tumbleweed-20220224.appx file

To start, rename the downloaded file so that it has a .ZIP extension instead of .APPX (or .APPXBUNDLE).

Screenshot of a downloaded openSUSE-Tumbleweed-20220224.appx file being actively renamed to .zip

Explorer will warn about changing the extension. Click Yes if you get that. You can then double-click the newly renamed ZIP. Inside, you’ll find multiple files, but you only need the application (EXE) and the install.tar.gz files.

Screenshot of zipped contents of openSUSE-Tumbleweed-20220224.zip with install.tar.gz and openSUSE-tumbleweed.exe highlighted

If you configured Explorer to show extensions, then can quickly spot the executable by the exe extension. Otherwise, it should distinguish itself by using the name of the Linux distribution. Extract these two files to your desired operating location (ex: C:\WSL).

Screenshot showing openSUSE-Tumbleweed-20220224.zip with install.tar.gz and openSUSE-tumbleweed.exe being dragged from a ZIP archive to C:\WSL

Now, you can double-click the extracted executable or run it from an elevated command prompt. Be warned that SmartScreen might not like it!

Screenshot of SmartScreen halting execution of openSUSE-Tumbleweed.exe

You can click More Info and Run anyway to get past this warning.

The distribution will then perform its installation routine.

Screenshot of openSUSE Tumbleweed installing in Windows Subsystem for Linux

When you exit from the session, you will notice that the installer created some supporting files, either in the same location or under your user’s profile.

Screenshot of the folder that contains an installed openSUSE WSL instance, with the rootfs, temp, and fsserver items outlined to draw focus

If using WSLv2, you will have a VHDX file instead of the rootfs folder. The temp folder will automatically recreate when necessary on each run of the distribution. Distributions may create their own files, such as the fsserver item that openSUSE created here. Leave those items and the executable that runs the distribution. You can delete the install.tar.gz file and any other support files that came from the APPX.

Going forward, you can run this executable or use the 

wsl

 command to start the distribution.

Adding the Distribution to the Path

The wsl.exe file lives in C:\Windows\System32, so you can invoke it from anywhere. With nothing else specified, doing so will start the default distribution. You can also pass the name of an installed distribution using 

-d

 and it will start that one. This is how you would run a command inside your distribution without loading the entire thing (ex 

wsl -d Ubuntu --ls /

). Such usage exceeds the intent of this article, so check the documentation link at the top for more information.

If you’d rather start your distribution by its executable, (ex ubuntu.exe), then you can add its location to your path. Microsoft’s document lists a convoluted way via PowerShell that did not work for me. Instead, use the age old technique at an elevated command prompt (not PowerShell):

PATH = %PATH%;C:\WSL\Ubuntu

Now you can just run 

ubuntu

 from any command prompt and it will start up your distro.

Screenshot of a Linux distribution successfully running after adding its path to the system's path environment variable

Want another cool trick? You can rename the exe and it will continue to work just fine.

ren C:\WSL\Ubuntu\ubuntu.exe my-cool-ubuntu.exe
Screenshot of a renamed WSL distribution running successfully

This does not change the behavior of wsl.exe in any way. You would still invoke this distribution with 

wsl -d Ubuntu

.

Go Forth and Linux on Windows Server

Future articles here on Project Runspace will use WSL for activities such as certificate services. Whatever your purpose, you now have the tools you need to run Windows Subsystem for Linux on your Windows Servers.

公司简介

 

自1996年以来,公司一直专注于域名注册、虚拟主机、服务器托管、网站建设、电子商务等互联网服务,不断践行"提供企业级解决方案,奉献个性化服务支持"的理念。作为戴尔"授权解决方案提供商",同时提供与公司服务相关联的硬件产品解决方案。
备案号: 豫ICP备05004936号-1

联系方式

地址:河南省郑州市经五路2号

电话:0371-63520088

QQ:76257322

网站:800188.com

电邮:该邮件地址已受到反垃圾邮件插件保护。要显示它需要在浏览器中启用 JavaScript。