Skip to content

Commit

Permalink
docs: update installation methods (#492)
Browse files Browse the repository at this point in the history
This removes the winget method from the installation instructions
because it is not currently well-supported.

It is replaced by a section on installing without the Microsoft Store,
as this is important to some users.
However, it is made clear that we do not currently recommend a specific
store from which to download images.

A brief section on running an instance of Ubuntu was also updated, as it
was previously tied to the winget section and did not use the latest
LTS.

UDENG-4097
  • Loading branch information
edibotopic authored Aug 29, 2024
2 parents e65c407 + de86b23 commit 88b23ba
Show file tree
Hide file tree
Showing 2 changed files with 23 additions and 17 deletions.
2 changes: 2 additions & 0 deletions docs/.custom_wordlist.txt
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
Appx
AppxPackage
awk
backports
Expand Down Expand Up @@ -28,6 +29,7 @@ js
Jupyter
localhost
LTS
MSIX
npm
Numbat
OpenGL
Expand Down
38 changes: 21 additions & 17 deletions docs/guides/install-ubuntu-wsl2.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
## What you will learn

* How to enable and install WSL on Windows 10 and Windows 11
* How to install `Ubuntu 24.04 LTS` using the Microsoft Store, WSL commands or the Winget package manager
* How to install `Ubuntu 24.04 LTS` using the Microsoft Store or WSL commands in the terminal

## What you will need

Expand All @@ -23,11 +23,11 @@ This command will enable the features necessary to run WSL and also install the

## Install Ubuntu WSL

WSL supports a variety of Linux distributions including the latest Ubuntu LTS release. Check out [the documentation](../reference/distributions.md) to see which one you prefer.
WSL supports a variety of Linux distributions including the latest Ubuntu LTS release. Check our [reference on distributions](../reference/distributions.md) to see which one you prefer.

There are multiple ways of installing distros on WSL, here we show three: Microsoft Store, WSL commands and the Winget package manager. The result is the same regardless of the method.
There are multiple ways of installing distros on WSL, here we focus on two: the Microsoft Store application and WSL commands run in the terminal. The result is the same regardless of the method.

### Method 1: Microsoft Store
### Method 1: Microsoft Store application

Find the distribution you prefer on the Microsoft Store and then click **Get**.

Expand All @@ -37,7 +37,7 @@ Ubuntu will then be installed on your machine. Once installed, you can either la

![Search results for Ubuntu 24.04 LTS in Windows search bar.](assets/install-ubuntu-wsl2/search-ubuntu-windows.png)

### Method 2: WSL commands
### Method 2: WSL commands in the terminal

It is possible to install the same Ubuntu versions available on the Microsoft Store directly from the command line.
In a PowerShell terminal, you can run `wsl --list --online` to see an output with all available distros and versions:
Expand Down Expand Up @@ -85,35 +85,39 @@ Use `wsl -l -v` to see all your currently installed distros and the version of W
* Ubuntu-24.04 Stopped 2
```

### Method 3: Win package manager
## Note on installing images without the Microsoft Store

Open a PowerShell terminal and type:
If you do not have access to the Microsoft Store or need to install
a custom image it is possible to import a distribution as a tar file:

```{code-block} text
> winget show --name Ubuntu --source msstore
> wsl --import <DistroName> <InstallLocation> <InstallTarFile>
```
Appx and MSIX packages for a given distro can also be downloaded and installed.
Please refer to Microsoft's documentation for more detailed information on these installation methods:

You'll see a list of available distros and their Ids. Choose the one you prefer and install it. For instance, for `Ubuntu 24.04 LTS`:
- [Importing Linux distributions](https://learn.microsoft.com/en-us/windows/wsl/use-custom-distro)
- [Installing distributions without the Microsoft Store](https://learn.microsoft.com/en-us/windows/wsl/install-manual#downloading-distributions)

```{code-block} text
> winget install --Id "9NZ3KLHXDJP5" --source msstore
```{warning}
You should always try to use the latest LTS release of Ubuntu, as it offers the best security, reliability and support when using Ubuntu WSL.
Currently we do not have a recommended store for downloading tar and Appx/MSIX files for Ubuntu distros.
```

You'll be prompted to accept the source and package agreements before installing. You need to accept them in order to proceed.
## Run and configure Ubuntu

Check out [the documentation](../reference/distributions.md) to see which executable matches your application and run it.
To open an Ubuntu 24.04 terminal run the following command in PowerShell:

```{code-block} text
> ubuntu.exe
> ubuntu2404.exe
```

## Configure Ubuntu

Congratulations, you now have an Ubuntu terminal running on your Windows machine.

Once it has finished its initial setup, you will be prompted to create a username and password. They don't need to match your Windows user credentials.

Finally, it’s always good practice to install the latest updates with the following commands, entering your password when prompted:
Finally, it’s always good practice to install the latest updates by running the following commands within the Ubuntu terminal, entering your password when prompted:

```{code-block} text
$ sudo apt update
Expand Down

0 comments on commit 88b23ba

Please sign in to comment.