Skip to content

Commit 26e532c

Browse files
author
Rich Turner
committed
Re-worked the WSL installation instructions
* Split common post-install initialization onto its own page * Split legacy distro instructions off onto its own page * Added legacy distro uninstallation instructions * Many wording improvements & a few tips * Added a few more illustrative screenshots * Improved several screenshots
1 parent bd0cd48 commit 26e532c

12 files changed

Lines changed: 231 additions & 103 deletions

‎WSL/curl-distro.png‎

17.5 KB
Loading

‎WSL/initialize-distro.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: Initialize a new WSL Linux distro
3+
description: After installing a Linux distro for WSL, complete initialization by following these simple steps
4+
keywords: BashOnWindows, bash, wsl, windows, windows subsystem for linux, windowssubsystem, ubuntu, debian, suse, windows 10
5+
author: taraj
6+
ms.author: taraj
7+
ms.date: 7/24/2018
8+
ms.topic: article
9+
ms.prod: windows-subsystem-for-linux
10+
ms.service: windows-subsystem-for-linux
11+
ms.assetid: 7afaeacf-435a-4e58-bff0-a9f0d75b8a51
12+
---
13+
14+
# Initializing a newly installed distro
15+
Once your distro has been downloaded and installed, you'll need to complete initialization of the new distro:
16+
17+
## Launch a distro
18+
To complete the initialization of your newly installed distro, launch a new instance. You can do this by clicking the "launch" button in the Windows Store app, or launching the distro from the Start menu:
19+
20+
> Tip: You might want to pin your most frequently used distros to your Start menu, and/or to your taskbar!
21+
22+
![Launch distros from the Start menu](media/start-menu.png)
23+
24+
> On Windows Server, you can launch your distro's launcher executable `<distro>.exe` from the distro installation folder.
25+
26+
The first time a newly installed distro runs, a Console window will open, and you'll be asked to wait for a minute or two for the installation to complete.
27+
28+
> During this final stage of installation, the distro's files are de-compressed and stored on your PC, ready for use. This may take around a minute or more depending on the performance of your PC's storage devices. This initial installation phase is only required when a distro is clean-installed - all future launches should take less than a second.
29+
30+
## Setting up a new Linux user account
31+
32+
Once installation is complete, you will be prompted to create a new user account (and its password).
33+
34+
![Ubuntu unpacking in the Windows console](media/UbuntuInstall.png)
35+
36+
This user account is for the normal non-admin user that you'll be logged-in as by default when launching a distro.
37+
38+
> You can choose any username and password you wish - they have no bearing on your Windows username.
39+
40+
When you open a new distro instance, you won't be prompted for your password, but **if you elevate a process using `sudo`, you will need to enter your password**, so make sure you choose a password you can easily remember! See the [User Support](user-support.md) page for more info.
41+
42+
## Update & upgrade your distro's packages
43+
44+
Most distros ship with an empty/minimal package catalog. We strongly recommend regularly updating your package catalog, and upgrading your installed packages using your distro's preferred package manager. On Debian/Ubuntu, you use apt:
45+
46+
``` bash
47+
sudo apt update && sudo apt upgrade
48+
```
49+
50+
> Windows does not automatically update or upgrade your Linux distro(s): This is a task that the Linux users prefer to control themselves.
51+
52+
You're done! Enjoy using your new Linux distro on WSL! To learn more about WSL, review the other [WSL docs](https://aka.ms/learnwsl), or the [WSL learning resources page](https://aka.ms/learnwsl).
53+
54+
![Enjoy using Linux on WSL](media/linux-on-wsl.png)
55+
56+
## Troubleshooting
57+
58+
Below are related errors and suggested fixes. Refer to the [WSL troubleshooting page](troubleshooting.md) for other common errors and their solutions.
59+
60+
> Installation failed with error 0x8007007e**
61+
> This error occurs when your system doesn't support Linux from the store. Make sure that:
62+
> * You're running Windows build 16215 or later. [Check your build](troubleshooting.md#check-your-build-number).
63+
> * The Windows Subsystem for Linux optional component is enabled and the computer has restarted. [Make sure WSL is enabled](troubleshooting.md#confirm-wsl-is-enabled).
64+

‎WSL/install-legacy.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: Install or remove the Linux Subsystem on Windows 10 Anniversary Update or Creators Update
3+
description: Installation and un-installation instructions for the legacy, beta distro on Windows 10 Anniversary Update or Creators Update
4+
keywords: BashOnWindows, bash, wsl, windows, windows subsystem for linux, windowssubsystem, ubuntu, debian, suse, windows 10, legacy, beta, install, remove, uninstall, un-install, delete, deprecated
5+
author: taraj
6+
ms.author: taraj
7+
ms.date: 7/24/2018
8+
ms.topic: article
9+
ms.prod: windows-subsystem-for-linux
10+
ms.service: windows-subsystem-for-linux
11+
ms.assetid: 7afaeacf-435a-4e58-bff0-a9f0d75b8a51
12+
---
13+
14+
# Windows 10 Anniversary Update and Creators Update WSL Install & Uninstall Guide
15+
If you're running Windows 10 Creators Update or later, please [follow the Windows 10 installation instructions](install-win10.md).
16+
17+
<strong><em><span style="color: #f28014">The following instructions are for users running Windows 10 Anniversary Update or Windows 10 Creators Update</span></em></strong>
18+
19+
Prior to Windows 10 Fall Creators Update (version 1709), WSL was released as a beta feature and installed a single Ubuntu instance when "Bash on Ubuntu on Windows" (or Bash.exe) was first run.
20+
21+
> While you CAN use WSL on earlier Windows 10 releases, this beta "legacy distro" is now considered obsolete. We strongly encourage you to run the most recent version of Windows 10 available. Each new Windows 10 release includes many hundreds of fixes and improvements in WSL alone, allowing ever more Linux tools and apps to run correctly on WSL.
22+
23+
If you cannot upgrade to Fall Creators Update or later, follow the steps below to enable and use WSL:
24+
25+
1. Turn on Developer Mode
26+
To run WSL on Windows 10 Anniversary Update or Creators Update, you must enable Developer Mode:
27+
28+
Open **Settings** -> **Update and Security** -> **For developers**
29+
30+
Select the Developer Mode radio button
31+
![Enable developer mode](media/updateAndSecurity.png)
32+
33+
> The requirement to enable Developer Mode was [removed in Windows 10 Fall Creators Update](https://blogs.msdn.microsoft.com/commandline/2017/06/08/developer-mode-no-longer-required-for-windows-subsystem-for-linux/)
34+
35+
1. Open a command prompt. Type `bash` and hit enter
36+
37+
The first time you run Bash on Ubuntu on Windows, you'll be prompted to accept Canonical's license. Once accpted, WSL will download and install the Ubuntu instance onto your machine, and a "Bash on Ubuntu on Windows" shortcut will be added to your start menu.
38+
39+
![Prompt to install Ubuntu](media/bashShellInstall.png)
40+
41+
The first time you run Bash on Ubuntu on Windows, you will be prompted to create a UNIX username and password. Follow the [new distro instance instructions](initialize-distro.md) to complete your installation
42+
43+
1. Launch a new Ubuntu shell by either:
44+
* Running `bash` from a command-prompt
45+
* Clicking the start menu "Bash on Ubuntu on Windows" shortcut
46+
47+
48+
# Uninstalling/Removing the legacy distro
49+
If you upgrade to Windows 10 Fall Creators Update from an earlier Windows 10 release upon which you installed WSL, your existing distro will remain intact. However, we STRONGLY encourage you to install a new Store-delivered distro ASAP, and migrate any necessary files, data, etc. from your legacy distro to your new distro.
50+
51+
To remove the legacy distro from your machine, run the following from a Command Line or PowerShell instance:
52+
53+
``` cmd
54+
lxrun /uninstall /full
55+
```
56+
57+
### Manually deleting the legacy distro
58+
If you wish, you can manually delete your legacy instance. This may be required if you encounter issues uninstalling the legacy distro using `lxrun.exe`, or are running Windows 10 Spring 2018 Update (or later) which do not ship with `lxrun.exe`.
59+
60+
To forcefully delete your legacy WSL distro, delete the `%localappdata%\lxss\` folder (and all it's sub-contents) using Windows' File Explorer, or the command-line:
61+
62+
Using PowerShell
63+
``` powershell
64+
rm -Recurse $env:localappdata/lxss/
65+
```
66+
67+
Using Cmd:
68+
``` cmd
69+
DEL /S %localappdata%\lxss\
70+
```

‎WSL/install-manual.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: Manually download Windows Subsystem for Linux (WSL) Distros
3+
description: Instructions for how to manually download WSL distros
4+
keywords: BashOnWindows, bash, wsl, windows, windows subsystem for linux, WSL, windowssubsystem, distro, ubuntu, openSUSE, SLES
5+
author: taraj
6+
ms.author: taraj
7+
ms.date: 07/24/2018
8+
ms.topic: article
9+
ms.prod: windows-subsystem-for-linux
10+
ms.service: windows-subsystem-for-linux
11+
ms.assetid: 9281ffa2-4fa9-4078-bf6f-b51c967617e3
12+
---
13+
# Manually download WSL distro packages
14+
15+
There are several scenarios in which you may not be able (or want) to, install WSL Linux distros via the Windows Store. Specifically, you may be running a Windows Server or Long-Term Servicing (LTSB/LTSC) desktop OS SKU that doesn't support Windows Store, or your corporate network policies and/or admins to not permit Windows Store usage in your environment.
16+
17+
In these cases, while WSL itself is available, how do you download and install Linux distros in WSL if you can't access the store?
18+
19+
> Note: **Command-Line shell environments including Cmd, PowerShell, and Linux/WSL distros are not permitted to run on Windows 10 S Mode**. This restriction exists in order to ensure the integrity and safety goals that S Mode delivers: Read [this post](https://blogs.msdn.microsoft.com/commandline/2017/05/18/will-linux-distros-run-on-windows-10-s/) for more information.
20+
21+
# Downloading distros
22+
23+
If the Windows Store app is not available, you can download and manually install Linux distros by clicking these links:
24+
* [Ubuntu](https://aka.ms/wsl-ubuntu-1604)
25+
* [OpenSUSE](https://aka.ms/wsl-opensuse-42)
26+
* [SLES](https://aka.ms/wsl-sles-12)
27+
28+
This will cause the `<distro>.appx` packages to download to a folder of your choosing. Follow the [installation instructions](#installing_your_distro) to install your downloaded distro(s).
29+
30+
## Downloading distros via the Command-Line
31+
If you prefer, you can also download your preferred distro(s) via the Command-Line:
32+
33+
### Download using PowerShell
34+
To download distros using PowerShell, use the [Invoke-WebRequest](https://msdn.microsoft.com/powershell/reference/5.1/microsoft.powershell.utility/invoke-webrequest) cmdlet. Here's a sample instruction to download Ubuntu 16.04.
35+
36+
``` PowerShell
37+
Invoke-WebRequest -Uri https://aka.ms/wsl-ubuntu-1604 -OutFile Ubuntu.appx -UseBasicParsing
38+
```
39+
40+
> [!TIP]
41+
> If the download is taking a long time, turn off the progress bar by setting `$ProgressPreference = 'SilentlyContinue'`
42+
43+
### Download using curl
44+
Windows 10 Spring 2018 Update (or later) includes the popular [curl command-line utility](https://curl.haxx.se/) with which you can invoke web requests (i.e. HTTP GET, POST, PUT, etc. commands) from the command-line. You can use `curl.exe` to download the above distro's:
45+
46+
``` cmd
47+
curl.exe -L -o ubuntu-1604.appx https://aka.ms/wsl-ubuntu-1604
48+
```
49+
50+
In the above example, `curl.exe` is executed (not just `curl`) to ensure that, in PowerShell, the real curl executable is invoked, not the PowerShell curl alias for [Invoke-WebRequest](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/invoke-webrequest?view=powershell-6)
51+
52+
> Note: Using `curl` might be preferable if you have to invoke/script download steps using Cmd shell and/or `.bat` / `.cmd` scripts.
53+
54+
# Installing your distro
55+
For instructions on how to install your downloaded distro(s), please refer to the [Windows Desktop](install-win10.md) or [Windows Server](install-on-server.md) installation instructions.

‎WSL/install-on-server.md‎

Lines changed: 18 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -17,68 +17,40 @@ ms.assetid: 9281ffa2-4fa9-4078-bf6f-b51c967617e3
1717
1818
At //Build2017, Microsoft announced that Windows Subsystem for Linux will be [available on Windows Server](https://blogs.technet.microsoft.com/hybridcloud/2017/05/10/windows-server-for-developers-news-from-microsoft-build-2017/). These instructions walk through running the Windows Subsystem for Linux on Windows Server 1709 and later.
1919

20-
## Enable the Windows Subsystem for Linux
20+
## Enable the Windows Subsystem for Linux (WSL)
2121

22-
Enable the "Windows Subsystem for Linux" optional feature and reboot.
22+
Before you can run Linux distros on Windows, you must enable the "Windows Subsystem for Linux" optional feature and reboot.
2323

2424
1. Open PowerShell as Administrator and run:
2525
``` PowerShell
2626
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
2727
```
2828
29-
2. Restart your computer when prompted.
29+
2. Restart your computer when prompted. **This reboot is required** in order to ensure that WSL can initiate a trusted execution environment.
3030
31+
## Download a Linux distro
3132
32-
## Install a Linux distribution
33+
Follow [these instructions](install-manual.md) to download your favorite Linux distribution.
3334
34-
1. Download the appx for your favorite Linux distribution.
35-
Here are links directly to the apps available through the store:
36-
* [Ubuntu](https://aka.ms/wsl-ubuntu-1604)
37-
* [OpenSUSE](https://aka.ms/wsl-opensuse-42)
38-
* [SLES](https://aka.ms/wsl-sles-12)
35+
## Extract and install a Linux distro
36+
Now that you've downloaded a distro, extract its contents and manually install the distro:
3937
40-
You can download the distributions to Windows Server with [`Invoke-WebRequest`](https://msdn.microsoft.com/powershell/reference/5.1/microsoft.powershell.utility/invoke-webrequest) cmdlet. Here's a sample instruction to download Ubuntu.
41-
42-
``` PowerShell
43-
Invoke-WebRequest -Uri https://aka.ms/wsl-ubuntu-1604 -OutFile ~/Ubuntu.zip -UseBasicParsing
44-
```
45-
46-
> [!TIP]
47-
> If the download is taking a long time, turn off the progress bar by setting `$ProgressPreference = 'SilentlyContinue'`
38+
1. Extract the `<distro>.appx` package's contents, e.g. using PowerShell:
4839
49-
50-
3. Unzip the file
5140
``` PowerShell
52-
Expand-Archive ~/Ubuntu.zip ~/Ubuntu
41+
Expand-Archive ~/Ubuntu.appx ~/Ubuntu
5342
```
54-
55-
Make sure your target directory (`~/Ubuntu` in this example) is on your system drive. Usually this is your C: drive.
56-
Example: `C:\Distros\Ubuntu`
57-
58-
The contents should look like this:
59-
![](media/server-appx-expand.png)
6043
61-
5. Run the installer, named `<distro>.exe`
62-
For example: `ubuntu.exe`, `fedora.exe`, etc.
44+
> Make sure your target directory (`~/Ubuntu` in this example) is on your system drive. Usually this is your `C:` drive. For example: `C:\Distros\Ubuntu`
6345
64-
> **Troubleshooting: Installation failed with error 0x8007007e**
65-
> This error occurs when your system doesn't support WSL. Make sure that:
66-
> * You're running Windows build 16215 or later. [Check your build](troubleshooting.md#check-your-build-number).
67-
> * The Windows Subsystem for Linux optional component is enabled and the computer has restarted. [Make sure WSL is enabled](troubleshooting.md#confirm-wsl-is-enabled).
46+
1. Run the distro launcher
47+
To complete installation, run the distro launcher application in the target folder, named `<distro>.exe`. For example: `ubuntu.exe`, etc.
6848
69-
4. Create a UNIX user
70-
71-
The first time you install the Windows Subsystem for Linux, you will be prompted to create a UNIX username and password.
72-
73-
This UNIX username and password can be different from, and has no relationship to, your Windows username and password. [Learn more about your UNIX account.](user-support.md).
74-
75-
5. Run distro's preferred update/upgrade.
76-
77-
``` BASH
78-
sudo apt-get update
79-
sudo apt-get upgrade
80-
```
49+
![Expanded Ubuntu distro on Windows Server](media/server-appx-expand.png)
8150
82-
You're done! Go use your new Linux environment!
51+
> **Troubleshooting**
52+
> * **Installation failed with error 0x8007007e**: This error occurs when your system doesn't support WSL. Make sure that:
53+
> * You're running Windows build 16215 or later. [Check your build](troubleshooting.md#check-your-build-number).
54+
> * The Windows Subsystem for Linux optional component is enabled and the computer has restarted. [Make sure WSL is enabled](troubleshooting.md#confirm-wsl-is-enabled).
8355
84-
![](media/server-cowsay.png)
56+
Now that your Linux distro is installed, you must [initialize your new distro instance](initialize-distro.md) before using your distro.

0 commit comments

Comments
 (0)