- Install Ubuntu on WSL2 on Windows 10
- 2. Install WSL
- 3. Download Ubuntu
- The one line install!
- 4. Configure Ubuntu
- 5. Install your first package
- 6. Customising your Terminal with Windows Terminal Preview
- 7. Enjoy Ubuntu on WSL!
- Further Reading
- Install Linux on Windows with WSL
- Prerequisites
- Install WSL command
- Change the default Linux distribution installed
- Set up your Linux user info
- Set up and best practices
- Check which version of WSL you are running
- Upgrade version from WSL 1 to WSL 2
- Ways to run multiple Linux distributions with WSL
- Want to try the latest WSL preview features?
- Additional resources
Install Ubuntu on WSL2 on Windows 10
NOTE: As of November 2022, the Windows 10 version of WSL has migrated to support the Windows Store application, bringing feature parity across Windows 10 and Windows 11. Please check out our updated Install Ubuntu on Windows 10 and Windows 11 tutorial for the latest information. This tutorial is now deprecated.
Windows Subsystem for Linux (WSL) allows you to install a complete Ubuntu terminal environment in minutes on your Windows machine, allowing you to develop cross-platform applications without leaving Windows.
In this tutorial, we’ll show you how to get up and running with Ubuntu on WSL. These instructions will work on both Windows 10 or Windows 11.
Whilst WSL is a powerful tool for all users, some features, such as the ability to run graphical Linux applications, are only available on Windows 11. Please check out our Windows 11 tutorial for more information.
2. Install WSL
Installing WSL is now easier than ever. Search for Windows PowerShell in your Windows search bar, then select Run as administrator.
At the command prompt type:
And wait for the process to complete.
For WSL to be properly activated, you will now need to restart your computer.
3. Download Ubuntu
WSL supports a variety of Linux distributions, including the latest Ubuntu release, Ubuntu 20.04 LTS and Ubuntu 18.04 LTS. You can find them by opening the Microsoft store app and searching for Ubuntu.
Choose the distribution you prefer and then click on Get as shown in the following screenshot:
Ubuntu will then install on your machine.
The one line install!
There is a single command that will install both WSL and Ubuntu at the same time.
When opening PowerShell for the first time, simply modify the initial instruction to:
This will install both WSL and Ubuntu! Don’t forget to restart your machine before continuing.
Once installed, you can either launch the application directly from the store or search for Ubuntu in your Windows search bar.
4. Configure Ubuntu
Congratulations, you now have an Ubuntu terminal running on your Windows machine!
If Ubuntu returns an error during this initial installation, then the most common issue is that virtualisation is disabled in your device’s BIOS menu. You will need to turn this on during your device’s boot sequence. The location of this option varies by manufacturer, so you will need to refer to their documentation to find it.
Once Ubuntu has finished its initial setup you will need to create a username and password (this does not 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.
Press Y when prompted.
5. Install your first package
Installing packages on Ubuntu is as easy as using a single command. Below, you will see how to install bpython, a simple python interpreter for trying out ideas, featuring some nice usability features like expected parameters and autocompletion.
To check that you have the latest package lists, type:
To run the application type:
6. Customising your Terminal with Windows Terminal Preview
Since you’re likely to be using your Ubuntu terminal a fair bit, it’s always nice to do some customisation. We recommend installing Windows Terminal Preview to get the most user-friendly setup. You can find it in the Microsoft Store.
Windows Terminal allows you to open multiple Terminal instances as tabs, so you can have PowerShell running alongside Ubuntu. It also includes a number of customisation options. In the below screenshot, we’ve changed the tab name and colour, and configured the terminal appearance to use the Tango Dark theme and the Ubuntu font!
These customisations can be applied universally using the Appearance menu in Settings or to individual profiles which each have their own Appearance menu. Try it yourself to find something you feel comfortable with!
7. Enjoy Ubuntu on WSL!
That’s it! In this tutorial, you’ve seen how to install WSL and Ubuntu, set up your profile, and install your first package. You also got some tips on how to customise your experience.
We hope you enjoy working with Ubuntu inside WSL. Don’t forget to check out our blog for the latest news on all things Ubuntu.
Further Reading
Install Linux on Windows with WSL
Developers can access the power of both Windows and Linux at the same time on a Windows machine. The Windows Subsystem for Linux (WSL) lets developers install a Linux distribution (such as Ubuntu, OpenSUSE, Kali, Debian, Arch Linux, etc) and use Linux applications, utilities, and Bash command-line tools directly on Windows, unmodified, without the overhead of a traditional virtual machine or dualboot setup.
Prerequisites
You must be running Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11 to use the commands below. If you are on earlier versions please see the manual install page.
Install WSL command
You can now install everything you need to run WSL with a single command. Open PowerShell or Windows Command Prompt in administrator mode by right-clicking and selecting «Run as administrator», enter the wsl —install command, then restart your machine.
This command will enable the features necessary to run WSL and install the Ubuntu distribution of Linux. (This default distribution can be changed).
If you’re running an older build, or just prefer not to use the install command and would like step-by-step directions, see WSL manual installation steps for older versions.
The first time you launch a newly installed Linux distribution, a console window will open and you’ll be asked to wait for files to de-compress and be stored on your machine. All future launches should take less than a second.
The above command only works if WSL is not installed at all, if you run wsl —install and see the WSL help text, please try running wsl —list —online to see a list of available distros and run wsl —install -d to install a distro. To uninstall WSL, see Uninstall legacy version of WSL or unregister or uninstall a Linux distribution.
Change the default Linux distribution installed
By default, the installed Linux distribution will be Ubuntu. This can be changed using the -d flag.
- To change the distribution installed, enter: wsl —install -d . Replace with the name of the distribution you would like to install.
- To see a list of available Linux distributions available for download through the online store, enter: wsl —list —online or wsl -l -o .
- To install additional Linux distributions after the initial install, you may also use the command: wsl —install -d .
If you want to install additional distributions from inside a Linux/Bash command line (rather than from PowerShell or Command Prompt), you must use .exe in the command: wsl.exe —install -d or to list available distributions: wsl.exe -l -o .
If you run into an issue during the install process, check the installation section of the troubleshooting guide.
To install a Linux distribution that is not listed as available, you can import any Linux distribution using a TAR file. Or in some cases, as with Arch Linux, you can install using an .appx file. You can also create your own custom Linux distribution to use with WSL.
Set up your Linux user info
Once you have installed WSL, you will need to create a user account and password for your newly installed Linux distribution. See the Best practices for setting up a WSL development environment guide to learn more.
Set up and best practices
We recommend following our Best practices for setting up a WSL development environment guide for a step-by-step walk-through of how to set up a user name and password for your installed Linux distribution(s), using basic WSL commands, installing and customizing Windows Terminal, set up for Git version control, code editing and debugging using the VS Code remote server, good practices for file storage, setting up a database, mounting an external drive, setting up GPU acceleration, and more.
Check which version of WSL you are running
You can list your installed Linux distributions and check the version of WSL each is set to by entering the command: wsl -l -v in PowerShell or Windows Command Prompt.
To set the default version to WSL 1 or WSL 2 when a new Linux distribution is installed, use the command: wsl —set-default-version , replacing with either 1 or 2.
To set the default Linux distribution used with the wsl command, enter: wsl -s or wsl —setdefault , replacing with the name of the Linux distribution you would like to use. For example, from PowerShell/CMD, enter: wsl -s Debian to set the default distribution to Debian. Now running wsl npm init from Powershell will run the npm init command in Debian.
To run a specific wsl distribution from within PowerShell or Windows Command Prompt without changing your default distribution, use the command: wsl -d , replacing with the name of the distribution you want to use.
Learn more in the guide to Basic commands for WSL.
Upgrade version from WSL 1 to WSL 2
New Linux installations, installed using the wsl —install command, will be set to WSL 2 by default.
The wsl —set-version command can be used to downgrade from WSL 2 to WSL 1 or to update previously installed Linux distributions from WSL 1 to WSL 2.
To see whether your Linux distribution is set to WSL 1 or WSL 2, use the command: wsl -l -v .
To change versions, use the command: wsl —set-version 2 replacing with the name of the Linux distribution that you want to update. For example, wsl —set-version Ubuntu-20.04 2 will set your Ubuntu 20.04 distribution to use WSL 2.
If you manually installed WSL prior to the wsl —install command being available, you may also need to enable the virtual machine optional component used by WSL 2 and install the kernel package if you haven’t already done so.
To learn more, see the Command reference for WSL for a list of WSL commands, Comparing WSL 1 and WSL 2 for guidance on which to use for your work scenario, or Best practices for setting up a WSL development environment for general guidance on setting up a good development workflow with WSL.
Ways to run multiple Linux distributions with WSL
WSL supports running as many different Linux distributions as you would like to install. This can include choosing distributions from the Microsoft Store, importing a custom distribution, or building your own custom distribution.
There are several ways to run your Linux distributions once installed:
- Install Windows Terminal(Recommended) Using Windows Terminal supports as many command lines as you would like to install and enables you to open them in multiple tabs or window panes and quickly switch between multiple Linux distributions or other command lines (PowerShell, Command Prompt, PowerShell, Azure CLI, etc). You can fully customize your terminal with unique color schemes, font styles, sizes, background images, and custom keyboard shortcuts. Learn more.
- You can directly open your Linux distribution by visiting the Windows Start menu and typing the name of your installed distributions. For example: «Ubuntu». This will open Ubuntu in it’s own console window.
- From Windows Command Prompt or PowerShell, you can enter the name of your installed distribution. For example: ubuntu
- From Windows Command Prompt or PowerShell, you can open your default Linux distribution inside your current command line, by entering: wsl.exe .
- From Windows Command Prompt or PowerShell, you can use your default Linux distribution inside your current command line, without entering a new one, by entering: wsl [command] . Replacing [command] with a WSL command, such as: wsl -l -v to list installed distributions or wsl pwd to see where the current directory path is mounted in wsl. From PowerShell, the command get-date will provide the date from the Windows file system and wsl date will provide the date from the Linux file system.
The method you select should depend on what you’re doing. If you’ve opened a WSL command line within a Windows Prompt or PowerShell window and want to exit, enter the command: exit .
Want to try the latest WSL preview features?
Try the most recent features or updates to WSL by joining the Windows Insiders Program. Once you have joined Windows Insiders, you can choose the channel you would like to receive preview builds from inside the Windows settings menu to automatically receive any WSL updates or preview features associated with that build. You can choose from:
- Dev channel: Most recent updates, but low stability.
- Beta channel: Ideal for early adopters, more reliable builds than the Dev channel.
- Release Preview channel: Preview fixes and key features on the next version of Windows just before its available to the general public.