diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 5438ee0c..24edec33 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -52,7 +52,12 @@ }, { "source_path": "wsl/user_support.md", - "redirect_url": "/windows/wsl/setup/environment#set-up-your-linux-user-info", + "redirect_url": "/windows/wsl/setup/environment#set-up-your-linux-username-and-password", + "redirect_document_id": false + }, + { + "source_path": "wsl/user-support.md", + "redirect_url": "/windows/wsl/setup/environment#set-up-your-linux-username-and-password", "redirect_document_id": false } ] diff --git a/WSL/basic-commands.md b/WSL/basic-commands.md index d9d1972b..05ba72c0 100644 --- a/WSL/basic-commands.md +++ b/WSL/basic-commands.md @@ -1,21 +1,16 @@ --- title: Basic commands for WSL description: Reference for the basic commands included with Windows Subsystem for Linux (WSL). -keywords: wsl, install, BashOnWindows, bash, windows subsystem for linux, install ubuntu on windows, enable WSL2, linux on windows -ms.date: 09/27/2021 +ms.date: 11/23/2021 ms.topic: article ms.localizationpriority: high --- -# Command reference for WSL +# Basic commands for WSL -The basic WSL commands below are listed in a format supported by PowerShell or Windows Command Prompt. To run these commands from a Bash / Linux distribution command line, you must replace `wsl` with `wsl.exe`. +The WSL commands below are listed in a format supported by PowerShell or Windows Command Prompt. To run these commands from a Bash / Linux distribution command line, you must replace `wsl` with `wsl.exe`. -## Basic commands - -The following basic commands are supported after [installing WSL](./install.md). - -### Install +## Install ```powershell wsl --install @@ -23,7 +18,7 @@ wsl --install Install WSL and the Ubuntu distribution of Linux. [Learn more](./install.md). -### Install a specific Linux distribution +## Install a specific Linux distribution ```powershell wsl --install --distribution @@ -31,7 +26,7 @@ wsl --install --distribution Designate a distribution of Linux for installation besides the default (Ubuntu) by replacing `` with the name of the distribution. This command can also be entered as: `wsl -d `. -### List available Linux distributions +## List available Linux distributions ```powershell wsl --list --online @@ -39,7 +34,7 @@ wsl --list --online See a list of the Linux distributions available through the online store. This command can also be entered as: `wsl -l -o`. -### List installed Linux distributions +## List installed Linux distributions ```powershell wsl --list --verbose @@ -47,7 +42,7 @@ wsl --list --verbose See a list of the Linux distributions installed on your Windows machine, including the state (whether the distribution is running or stopped) and the version of WSL running the distribution (WSL 1 or WSL 2). [Comparing WSL 1 and WSL 2](./compare-versions.md). This command can also be entered as: `wsl -l -v`. Additional options that can be used with the list command include: `--all` to list all distributions, `--running` to list only distributions that are currently running, or `--quite` to only show distribution names. -### Set WSL version to 1 or 2 +## Set WSL version to 1 or 2 ```powershell wsl --set-version @@ -55,7 +50,7 @@ wsl --set-version To designate the version of WSL (1 or 2) that a Linux distribution is running on, replace `` with the name of the distribution and replace `` with 1 or 2. [Comparing WSL 1 and WSL 2](./compare-versions.md). -### Set default WSL version +## Set default WSL version ```powershell wsl --set-default-version @@ -63,7 +58,7 @@ wsl --set-default-version To set a default version of WSL 1 or WSL 2, replacing `` with either the number 1 or 2 to represent which version of WSL you would like the installation to default on for new Linux distribution installations. For example, `wsl --set-default-version 2`. [Comparing WSL 1 and WSL 2](./compare-versions.md). -### Set default Linux distribution +## Set default Linux distribution ```powershell wsl --set-default @@ -71,7 +66,15 @@ wsl --set-default To set the default Linux distribution that WSL commands will use to run, replace `` with the name of your preferred Linux distribution. -### Run a specific Linux distribution from PowerShell or CMD +## Change directory to home + +```powershell +wsl ~ +``` + +The `~` can be used with wsl to start in the user's home directory. To jump from any directory back to home from within a WSL command prompt, you can use the command: `cd ~`. + +## Run a specific Linux distribution from PowerShell or CMD ```powershell wsl --distribution --user @@ -79,7 +82,7 @@ wsl --distribution --user To run a specific Linux distribution with a specific user, replace `` with the name of your preferred Linux distribution (ie. Debian) and `` with the name of an existing user (ie. root). If the user doesn't exist in the WSL distribution, you will receive an error. To print the current user name, use the command `whoami`. -### Update WSL +## Update WSL ```powershell wsl --update @@ -87,7 +90,7 @@ wsl --update Manually update the version of your WSL Linux kernel. You can also use the command: `wsl --update rollback` to rollback to a previous version of the WSL Linux kernel. -### Check WSL status +## Check WSL status ```powershell wsl --status @@ -95,7 +98,7 @@ wsl --status See general information about your WSL configuration, such as default distribution type, default distribution, and kernel version. -### Help command +## Help command ```powershell wsl --help @@ -103,15 +106,29 @@ wsl --help See a list of options and commands available with WSL. -### Home directory +## Run as a specific user ```powershell -wsl ~ +wsl -u `, `wsl --user ``` -The `~` can be used with wsl to start in the user's home directory. To jump from any directory back to home from within a WSL command prompt, you can use the command: `cd ~`. +To run WSL as a specified user, replace `` with the name of a user that exists in the WSL distribution. -### Shutdown +## Change the default user for a distribution + +```powershell + config --default-user +``` + +Change the default user for your distribution log-in. The user has to already exist inside the distribution in order to become the default user. + +For example: +`ubuntu config --default-user johndoe` would change the default user for the Ubuntu distribution to the "johndoe" user. + +> [!NOTE] +> If you are having trouble figuring out the name of your distribution, use the command `wsl -l`. + +## Shutdown ```powershell wsl --shutdown @@ -119,7 +136,7 @@ wsl --shutdown Immediately terminates all running distributions and the WSL 2 lightweight utility virtual machine. This command may be necessary in instances that require you to restart the WSL 2 virtual machine environment, such as [changing memory usage limits](./vhd-size.md) or making a change to your [.wslconfig file](./manage.md#). -### Terminate +## Terminate ```powershell wsl --terminate @@ -127,7 +144,7 @@ wsl --terminate To terminate the specified distribution, or stop it from running, replace `` with the name of the targeted distribution. -### Export a distribution to a TAR file +## Export a distribution to a TAR file ```powershell wsl --export @@ -135,7 +152,7 @@ wsl --export Exports the distribution to a tar file. The filename can be - for standard output. -### Import a new distribution +## Import a new distribution ```powershell wsl --import @@ -143,13 +160,19 @@ wsl --import Imports the specified tar file as a new distribution. The filename can be - for standard input. The `--version` option can also be used with this command to designate whether the imported distribution will run on WSL 1 or WSL 2. -### Unregister or uninstall a Linux distribution +## Unregister or uninstall a Linux distribution + +While Linux distributions can be installed through the Microsoft Store, they can't be uninstalled through the store. + +To unregister and uninstall a WSL distribution: ```powershell -wsl --unregister +wsl --unregister ``` -Unregister or uninstall the specific distribution by replacing `` with the name of the targeted distribution. This will remove the distribution from WSL and delete all of the associated data. You can also uninstall the Linux distribution app on your Windows machine just like any other store application. +Replacing `` with the name of your targeted Linux distribution will unregister that distribution from WSL so it can be reinstalled or cleaned up. **Caution:** Once unregistered, all data, settings, and software associated with that distribution will be permanently lost. Reinstalling from the store will install a clean copy of the distribution. For example, `wsl --unregister Ubuntu` would remove Ubuntu from the distributions available in WSL. Running `wsl --list` will reveal that it is no longer listed. + +You can also uninstall the Linux distribution app on your Windows machine just like any other store application. To reinstall, find the distribution in the Microsoft Store and select "Launch". ## Mount a disk or device diff --git a/WSL/compare-versions.md b/WSL/compare-versions.md index e4b14074..32a93f1f 100644 --- a/WSL/compare-versions.md +++ b/WSL/compare-versions.md @@ -1,15 +1,15 @@ --- title: Comparing WSL 1 and WSL 2 -description: Compare version 1 and version 2 of the Windows Subsystem for Linux. Learn whats new in WSL 2. -keywords: BashOnWindows, bash, wsl, windows, windowssubsystem, gnu, linux, ubuntu, debian, suse, windows 10, UX changes, WSL 2, linux kernel, network applications, localhost, IPv6, Virtual Hardware Disk, VHD, VHD limitations, VHD error -ms.date: 09/27/2021 +description: WSL 2 provides the benefits of WSL 1, but uses an actual Linux kernel, rather than a translation layer like WSL 1, resulting in faster performance. +ms.date: 11/22/2021 ms.topic: conceptual +ms.custom: seo-windows-dev ms.localizationpriority: high --- # Comparing WSL 1 and WSL 2 -The primary difference and reasons for updating the Windows Subsystem for Linux from WSL 1 to WSL 2 are to: +The primary reasons to [update from WSL 1 to WSL 2](./install.md#upgrade-version-from-wsl-1-to-wsl-2) are to: - **increase file system performance**, - **support full system call compatibility**. @@ -19,6 +19,8 @@ WSL 2 uses the latest and greatest in virtualization technology to run a Linux k > [!div class="nextstepaction"] > [Install WSL](install.md) +This guide will compare WSL 1 and WSL 2, including [exceptions for using WSL 1 rather than WSL 2](#exceptions-for-using-wsl-1-rather-than-wsl-2). The primary differences between WSL 1 and WSL 2 are the use of an actual Linux kernel inside a managed VM, support for full system call compatibility, and performance across the Linux and Windows operating systems. + ## Comparing features Feature | WSL 1 | WSL 2 @@ -32,7 +34,7 @@ Feature | WSL 1 | WSL 2 Full system call compatibility| ❌ | ✅ Performance across OS file systems| ✅ | ❌ -As you can tell from the comparison table above, the WSL 2 architecture outperforms WSL 1 in several ways, with the exception of performance across OS file systems. +As you can tell from the comparison table above, the WSL 2 architecture outperforms WSL 1 in several ways, with the exception of performance across OS file systems, which can be addressed by storing your project files on the same operating system as the tools you are running to work on the project. WSL 2 is only available in Windows 10, Version 1903, Build 18362 or higher. Check your Windows version by selecting the **Windows logo key + R**, type **winver**, select **OK**. (Or enter the `ver` command in Windows Command Prompt). You may need to [update to the latest Windows version](ms-settings:windowsupdate). For builds lower than 18362, WSL is not supported at all. @@ -59,6 +61,8 @@ The Linux kernel in WSL 2 is built by Microsoft from the latest stable branch, b The [WSL 2 Linux kernel is open source](https://github.com/microsoft/WSL2-Linux-Kernel). If you'd like to learn more, check out the blog post [Shipping a Linux Kernel with Windows](https://devblogs.microsoft.com/commandline/shipping-a-linux-kernel-with-windows/) written by the team that built it. +Learn more in the [Release Notes for Windows Subsystem for Linux kernel](./kernel-release-notes.md). + ### Increased file IO performance File intensive operations like git clone, npm install, apt update, apt upgrade, and more are all noticeably faster with WSL 2. @@ -85,6 +89,8 @@ We recommend that you use WSL 2 as it offers faster performance and 100% system - WSL 2 does not include support for accessing serial ports. Learn more in the [FAQs](./faq.yml#can-i-access-the-gpu-in-wsl-2--are-there-plans-to-increase-hardware-support-) or in [WSL GitHub repo issue on serial support](https://github.com/microsoft/WSL/issues/4322). - You have strict memory requirements - WSL 2's memory usage grows and shrinks as you use it. When a process frees memory this is automatically returned to Windows. However, as of right now WSL 2 does not yet release cached pages in memory back to Windows until the WSL instance is shut down. If you have long running WSL sessions, or access a very large amount of files, this cache can take up memory on Windows. We are tracking the work to improve this experience on [the WSL Github repository issue 4166](https://github.com/microsoft/WSL/issues/4166). +- For those using VirtualBox, you may need to consider the version that you are running and whether it is compatible with WSL 2. (See [WSL Github repository issue 798](https://github.com/MicrosoftDocs/WSL/issues/798) for the full discussion. It appears that VirtualBox v6.1.16 works will with WSL 2, but that other versions may experience issues.) +- If you rely on a Linux distribution to have an IP address in the same network as your host machine, you may need to set up a workaround in order to run WSL 2. WSL 2 is running as a hyper-v virtual machine. This is a change from the bridged network adapter used in WSL 1, meaning that WSL 2 uses a Network Address Translation (NAT) service for it's virtual network, instead of making it bridged to the host Network Interface Card (NIC) resulting in a unique IP address that will change on restart. To learn more about the issue and workaround that forwards TCP ports of WSL 2 services to the host OS, see [WSL GitHub repository issue 4150, NIC Bridge mode (TCP Workaround)](https://github.com/microsoft/WSL/issues/4150). > [!NOTE] > Consider trying the VS Code [Remote WSL Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) to enable you to store your project files on the Linux file system, using Linux command line tools, but also using VS Code on Windows to author, edit, debug, or run your project in an internet browser without any of the performance slow-downs associated with working across the Linux and Windows file systems. [Learn more](tutorials/wsl-vscode.md). diff --git a/WSL/index.md b/WSL/index.md index f55dc916..26023f98 100644 --- a/WSL/index.md +++ b/WSL/index.md @@ -1,30 +1,32 @@ --- title: Windows Subsystem for Linux Documentation -description: Explore the Windows Subsystem for Linux documentation. -keywords: wsl docs, BashOnWindows, bash, wsl, windows, windowssubsystem, gnu, linux -ms.topic: article -ms.date: 09/27/2021 +description: Overview of the Windows Subsystem for Linux documentation. +ms.topic: overview +ms.date: 12/06/2021 ms.localizationpriority: high +ms.custom: seo-windows-dev --- # Windows Subsystem for Linux Documentation -The Windows Subsystem for Linux lets developers run a GNU/Linux environment -- including most command-line tools, utilities, and applications -- directly on Windows, unmodified, without the overhead of a traditional virtual machine or dual-boot setup. +Windows Subsystem for Linux (WSL) lets developers run a GNU/Linux environment -- including most command-line tools, utilities, and applications -- directly on Windows, unmodified, without the overhead of a traditional virtual machine or dual-boot setup. > [!div class="nextstepaction"] > [Install WSL](install.md) ## Learn more -* [What is the Windows Subsystem for Linux?](about.md) +* [What is the Windows Subsystem for Linux (WSL)?](about.md) * [What's new with WSL 2?](compare-versions.md#whats-new-in-wsl-2) -* [Compare WSL 2 and WSL 1](compare-versions.md) -* [Read frequently asked questions](faq.yml) +* [Comparing WSL 1 and WSL 2](compare-versions.md) +* [Frequently Asked Questions](faq.yml) ## Get started * [Install WSL](install.md) * [Install Linux on Windows Server](install-on-server.md) +* [Manual install steps](install-manual.md) +* [Best practices for setting up a WSL development environment](./setup/environment.md) ## Try WSL preview features by joining the Windows Insiders Program @@ -40,12 +42,7 @@ To try the most recent features or updates to WSL, join the [Windows Insiders Pr * [Command-Line blog](https://blogs.msdn.microsoft.com/commandline/) (Active) * [Windows Subsystem for Linux Blog](/archive/blogs/wsl/) (Historical) -## Posts and articles - -* [Run Bash on Ubuntu on Windows](https://blogs.windows.com/buildingapps/2016/03/30/run-bash-on-ubuntu-on-windows/) -* [Developers Can Run Bash And Usermode Ubuntu Linux Binaries On Windows 10](https://www.hanselman.com/blog/DevelopersCanRunBashShellAndUsermodeUbuntuLinuxBinariesOnWindows10.aspx) -* [Ubuntu on Windows – The Ubuntu Userspace for Windows Developers](https://insights.ubuntu.com/2016/03/30/ubuntu-on-windows-the-ubuntu-userspace-for-windows-developers/) - ## Provide feedback -* [GitHub issue tracker](https://github.com/Microsoft/BashOnWindows/issues) \ No newline at end of file +* [GitHub issue tracker: WSL](https://github.com/microsoft/WSL/issues) +* [GitHub issue tracker: WSL documentation](https://github.com/MicrosoftDocs/WSL/issues) diff --git a/WSL/install-manual.md b/WSL/install-manual.md index 19a004c2..e5fc22d2 100644 --- a/WSL/install-manual.md +++ b/WSL/install-manual.md @@ -98,7 +98,7 @@ wsl --set-default-version 2 The first time you launch a newly installed Linux distribution, a console window will open and you'll be asked to wait for a minute or two for files to de-compress and be stored on your PC. All future launches should take less than a second. -You will then need to [create a user account and password for your new Linux distribution](./setup/environment.md#set-up-your-linux-user-info). +You will then need to [create a user account and password for your new Linux distribution](./setup/environment.md#set-up-your-linux-username-and-password). ![Ubuntu unpacking in the Windows console](media/UbuntuInstall.png) @@ -153,7 +153,7 @@ Add-AppxPackage .\app_name.appx If you are using Windows server, or run into problems running the command above you can find the alternate install instructions on the [Windows Server](install-on-server.md) documentation page to install the `.appx` file by changing it to a zip file. -Once your distribution is installed, follow the instructions to [create a user account and password for your new Linux distribution](./setup/environment.md#set-up-your-linux-user-info). +Once your distribution is installed, follow the instructions to [create a user account and password for your new Linux distribution](./setup/environment.md#set-up-your-linux-username-and-password). ## Install Windows Terminal (optional) diff --git a/WSL/install-on-server.md b/WSL/install-on-server.md index e2523856..6ba08766 100644 --- a/WSL/install-on-server.md +++ b/WSL/install-on-server.md @@ -52,4 +52,4 @@ $userenv = [System.Environment]::GetEnvironmentVariable("Path", "User") You can now launch your distribution from any path by typing `.exe`. For example: `ubuntu.exe`. -Once installation is complete, you can [create a user account and password for your new Linux distribution](./setup/environment.md#set-up-your-linux-user-info). +Once installation is complete, you can [create a user account and password for your new Linux distribution](./setup/environment.md#set-up-your-linux-username-and-password). diff --git a/WSL/install.md b/WSL/install.md index 8975fcee..53f1c796 100644 --- a/WSL/install.md +++ b/WSL/install.md @@ -1,8 +1,7 @@ --- title: Install WSL description: Install Windows Subsystem for Linux with the command, wsl --install. Use a Bash terminal on your Windows machine run by your preferred Linux distribution - Ubuntu, Debian, SUSE, Kali, Fedora, Pengwin, Alpine, and more are available. -keywords: wsl, install, BashOnWindows, bash, windows subsystem for linux, install ubuntu on windows, enable WSL2, linux on windows -ms.date: 09/27/2021 +ms.date: 11/22/2021 ms.topic: article ms.localizationpriority: high --- @@ -45,11 +44,45 @@ If you run into an issue during the install process, check the [installation sec ## 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](./setup/environment.md#set-up-your-linux-user-info) guide to learn more. +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](./setup/environment.md#set-up-your-linux-username-and-password) guide to learn more. ## Set up and best practices -We recommend following our [Best practices for setting up a WSL development environment](./setup/environment.md) 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. +We recommend following our [Best practices for setting up a WSL development environment](./setup/environment.md) 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](./basic-commands.md). + +## Upgrade version from WSL 1 to WSL 2 + +To update from WSL 1 to WSL 2 on previously installed Linux distributions, 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. You may also need to [enable the virtual machine optional component](./install-manual.md#step-3---enable-virtual-machine-feature) used by WSL 2 and [install the kernel package](./install-manual.md#step-4---download-the-linux-kernel-update-package) if you haven't already done so. + +New Linux installations will be set to WSL 2 by default, but the `wsl --set-version` command can be used to downgrade from WSL 2 to WSL 1 as well. To see whether your Linux distribution is set to WSL 1 or WSL 2, use the command: `wsl -l -v`. + +To learn more, see the [Command reference for WSL](./basic-commands.md) for a list of WSL commands, [Comparing WSL 1 and WSL 2](./compare-versions.md) for guidance on which to use for your work scenario, or [Best practices for setting up a WSL development environment](./setup/environment.md) 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](https://aka.ms/wslstore), [importing a custom distribution](./use-custom-distro.md), or [building your own custom distribution](./build-custom-distro.md). + +There are several ways to run your Linux distributions once installed: + +1. [Install Windows Terminal](/windows/terminal/get-started) ***(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.](/windows/terminal) +2. 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. +3. From Windows Command Prompt or PowerShell, you can enter the name of your installed distribution. For example: `ubuntu` +4. From Windows Command Prompt or PowerShell, you can open your default Linux distribution inside your current command line, by entering: `wsl.exe`. +5. 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? diff --git a/WSL/media/AppStorage.png b/WSL/media/appstorage.png similarity index 100% rename from WSL/media/AppStorage.png rename to WSL/media/appstorage.png diff --git a/WSL/media/bashShellInstall.png b/WSL/media/bashShellInstall.png deleted file mode 100644 index 5c3ac533..00000000 Binary files a/WSL/media/bashShellInstall.png and /dev/null differ diff --git a/WSL/media/bash_logo.png b/WSL/media/bash_logo.png deleted file mode 100644 index 744ce134..00000000 Binary files a/WSL/media/bash_logo.png and /dev/null differ diff --git a/WSL/media/linux-on-wsl.png b/WSL/media/linux-on-wsl.png deleted file mode 100644 index 15cfb3d2..00000000 Binary files a/WSL/media/linux-on-wsl.png and /dev/null differ diff --git a/WSL/media/server-bash-install.png b/WSL/media/server-bash-install.png deleted file mode 100644 index a6712c1c..00000000 Binary files a/WSL/media/server-bash-install.png and /dev/null differ diff --git a/WSL/media/server-cowsay.png b/WSL/media/server-cowsay.png deleted file mode 100644 index 2657e0ab..00000000 Binary files a/WSL/media/server-cowsay.png and /dev/null differ diff --git a/WSL/media/start-launch.png b/WSL/media/start-launch.png deleted file mode 100644 index 21fc9d65..00000000 Binary files a/WSL/media/start-launch.png and /dev/null differ diff --git a/WSL/media/start-menu.png b/WSL/media/start-menu.png deleted file mode 100644 index 356e51e4..00000000 Binary files a/WSL/media/start-menu.png and /dev/null differ diff --git a/WSL/setup/environment.md b/WSL/setup/environment.md index be181d6b..a29e3fe0 100644 --- a/WSL/setup/environment.md +++ b/WSL/setup/environment.md @@ -1,18 +1,18 @@ --- -title: Best practices for setting up a WSL 2 development environment -description: A step-by-step guide to help you set up a WSL 2 development environment using Ubuntu, Visual Studio Code or Visual Studio, Git, Windows Credential Manager, and with recommended tutorials. -keywords: Best practices, wsl, wsl 2, windows subsystem for linux, set up your dev environment with wsl 2, development environment, set up wsl 2 -ms.date: 09/27/2021 +title: Set up a WSL development environment +description: Set up a WSL development environment using best practices from this set-by-step guide. Learn how to run Ubuntu, Visual Studio Code or Visual Studio, Git, Windows Credential Manager, MongoDB, MySQL, Docker remote containers and more. +ms.date: 12/06/2021 ms.topic: article ms.localizationpriority: medium no-loc: [Terminal] +ms.custom: seo-windows-dev --- -# Best practices for setting up a WSL development environment +# Set up a WSL development environment -A step-by-step guide to help you set up a WSL development environment using Ubuntu, Visual Studio Code or Visual Studio, Git, Windows Credential Manager, and with recommended tutorials for everything you might want. +A step-by-step guide to the best practices for setting up a WSL development environment. Learn how to run the command to install the default Bash shell that uses Ubuntu or can be set to install other Linux distributions, use basic WSL commands, set up Visual Studio Code or Visual Studio, Git, Windows Credential Manager, databases like MongoDB, Postgres, or MySQL, set up GPU acceleration, run GUI apps, and more. -## Install WSL +## Get started Windows Subsystem for Linux comes with the Windows operating system, but you must enable it and install a Linux distribution before you can begin using it. @@ -39,7 +39,7 @@ You will need to restart your machine during this installation process. Check the [troubleshooting installation](../troubleshooting.md) article if you run into any issues. -## Set up your Linux user info +## Set up your Linux username and password Once the process of installing your Linux distribution with WSL is complete, open the distribution (Ubuntu by default) using the Start menu. You will be asked to create a **User Name** and **Password** for your Linux distribution. @@ -182,6 +182,10 @@ Follow this step-by-step guide to [Get started mounting a Linux disk in WSL 2](. ![wsl mount command screenshot](../media/wslmountsimple.png) +## Run Linux GUI apps + +Follow this tutorial to learn how to set up and [run Linux GUI apps on WSL](../tutorials/gui-apps.md). + ## Additional resources - [Set up your development environment on Windows](/windows/dev-environment/): Learn more about setting up your development environment for your preferred language or framework, such as React, Python, NodeJS, Vue, etc. diff --git a/WSL/troubleshooting.md b/WSL/troubleshooting.md index 545df5bf..bcb0953c 100644 --- a/WSL/troubleshooting.md +++ b/WSL/troubleshooting.md @@ -29,7 +29,7 @@ You can also: - **Installation failed with error 0x80070003** - The Windows Subsystem for Linux only runs on your system drive (usually this is your `C:` drive). Make sure that distributions are stored on your system drive: - Open **Settings** -> **System** --> **Storage** -> **More Storage Settings: Change where new content is saved** - ![Picture of system settings to install apps on C: drive](media/AppStorage.png) + ![Picture of system settings to install apps on C: drive](media/appstorage.png) - **WslRegisterDistribution failed with error 0x8007019e** - The Windows Subsystem for Linux optional component is not enabled: diff --git a/WSL/user-support.md b/WSL/user-support.md deleted file mode 100644 index 707288e3..00000000 --- a/WSL/user-support.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Create user account for Linux distribution -description: Reference for user accounts and permission management with the Windows Subsystem for Linux. -keywords: BashOnWindows, bash, wsl, windows, windows subsystem for linux, windowssubsystem, ubuntu, user accounts -ms.date: 09/27/2021 -ms.topic: article -ms.localizationpriority: high ---- - -# Create a user account and password for your new Linux distribution - -Once you have [enabled WSL and installed a Linux distribution from the Microsoft Store](./install.md), the first step you will be asked to complete when opening your newly installed Linux distribution is to create an account, including a **User Name** and **Password**. - -- This **User Name** and **Password** is specific to each separate Linux distribution that you install and has no bearing on your Windows user name. - -- Once you create a **User Name** and **Password**, the account will be your default user for the distribution and automatically sign-in on launch. - -- This account will be considered the Linux administrator, with the ability to run `sudo` (Super User Do) administrative commands. - -- Each Linux distribution running on the Windows Subsystem for Linux has its own Linux user accounts and passwords. You will have to configure a Linux user account every time you add a distribution, reinstall, or reset. - -![Ubuntu unpacking in the Windows console](media/UbuntuInstall.png) - -> [!NOTE] -> Linux distributions installed with WSL are a per-user installation and can't be shared with other Windows user accounts. - -## Update and upgrade packages - -Most distributions ship with an empty or minimal package catalog. We strongly recommend regularly updating your package catalog and upgrading your installed packages using your distribution's preferred package manager. For Debian/Ubuntu, use apt: - -```bash -sudo apt update && sudo apt upgrade -``` - -Windows does not automatically update or upgrade your Linux distribution(s). This is a task that most Linux users prefer to control themselves. - -## Reset your Linux password - -To change your password, open your Linux distribution (Ubuntu for example) and enter the command: `passwd` - -You will be asked to enter your current password, then asked to enter your new password, and then to confirm your new password. - -## Forgot your password - -If you forgot the password for your Linux distribution: - -1. Open PowerShell and enter the root of your default WSL distribution using the command: `wsl -u root` - - > If you need to update the forgotten password on a distribution that is not your default, use the command: `wsl -d Debian -u root`, replacing `Debian` with the name of your targeted distribution. - -2. Once your WSL distribution has been opened at the root level inside PowerShell, you can use this command to update your password: `passwd ` where `` is the username of the account in the DISTRO whose password you've forgotten. - -3. You will be prompted to enter a new UNIX password and then confirm that password. Once you're told that the password has updated successfully, close WSL inside of PowerShell using the command: `exit` - -> [!NOTE] -> If you are running an early version of Windows operating system, like 1703 (Creators Update) or 1709 (Fall Creators Update), see the [Using older version of Windows and WSL](./troubleshooting.md#using-older-versions-of-windows-and-wsl) in the Troubleshooting guide. diff --git a/WSL/wsl-config.md b/WSL/wsl-config.md index c6dc5fac..a362733b 100644 --- a/WSL/wsl-config.md +++ b/WSL/wsl-config.md @@ -1,156 +1,105 @@ --- -title: Configure Linux distributions -description: A reference guide to help you manage and configure multiple Linux distributions running on the Windows Subsystem for Linux. -keywords: BashOnWindows, bash, wsl, windows, windows subsystem for linux, windowssubsystem, ubuntu, wsl.conf, wslconfig -ms.date: 09/27/2021 +title: Advanced settings configuration in WSL +description: A guide to the wsl.conf and .wslconfig files used for configuring settings when running multiple Linux distributions on Windows Subsystem for Linux. +ms.date: 12/02/2021 ms.topic: article +ms.custom: seo-windows-dev --- -# Configure Linux distributions +# Advanced settings configuration in WSL -Windows Subsystem for Linux (WSL) supports running as many different Linux distributions as you would like to install. This can include choosing distributions from the [Microsoft Store](https://aka.ms/wslstore), [importing a custom distribution](./use-custom-distro.md), or [building your own custom distribution](./build-custom-distro.md). +The [wsl.conf](#wslconf) and [.wslconfig](#wslconfig) files are used to configure advanced settings options, on a per-distribution basis (`wsl.conf`) and globally across all WSL 2 distributions (`.wslconfig`). This guide will cover each of the settings options, when to use each file type, where to store the file, sample settings files and tips. -## Ways to run WSL +## What is the difference between wsl.conf and .wslconfig? -There are several ways to run a Linux distribution with WSL once it's installed: +You can configure the settings for your installed Linux distributions that will automatically be applied every time you launch WSL in two ways, by using: -1. The number one way that we recommend you run Linux distributions is by [installing Windows Terminal](/windows/terminal/get-started). Using Windows Terminal enables you to open multiple tabs or window panes to display 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.](/windows/terminal) -2. 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. -3. From Windows Command Prompt or PowerShell, you can enter the name of your installed distribution. For example: `ubuntu` -4. From Windows Command Prompt or PowerShell, you can open your default Linux distribution inside your current command line, by entering: `wsl.exe`. -5. 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. +- **[.wslconfig](#wslconfig)** to configure settings **globally** across all installed distributions running on WSL 2. +- **[wsl.conf](#wslconf)** to configure settings **per-distribution** for Linux distros running on WSL 1 or WSL 2. -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`. +Both file types are used for configuring WSL settings, but the location where the file is stored, the scope of the configuration, and the version of WSL running your distribution all impact which file type to choose. -![Launch WSL from Start menu](media/start-launch.png) +The version of WSL that you are running will impact the configuration settings. WSL 2 runs as a lightweight virtual machine (VM), so uses virtualization settings that allow you to control the amount of memory or processors used (which may be familiar if you use Hyper-V or VirtualBox). -## List installed distributions +## wsl.conf -To see a list of the Linux distributions you have installed, enter: `wsl --list` or `wsl -l -v` for a verbose list. To set an installed Linux distribution as the default that is 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, 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. +- Stored in the `/etc` directory of the distribution. +- Used to configure settings on a per-distribution basis. Settings configured in this file will only be applied to the specific Linux distribution that contains the directory where this file is stored. +- Can be used for distributions run by either version, WSL 1 or WSL 2. +- To get to the `/etc` directory for an installed distribution, use the distribution's command line with `cd /` to access the root directory, then `ls` to list files or `explorer.exe .` to view in Windows File Explorer. The directory path should look something like: `/etc/wsl.conf`. -## Unregister and reinstall a distribution +## .wslconfig -While Linux distributions can be installed through the Microsoft Store, they can't be uninstalled through the store. +- Stored in your `%UserProfile%` directory. +- Used to configure settings globally across all installed Linux distributions running as the WSL 2 version. +- Can be used **only for distributions run by WSL 2**. Distributions running as WSL 1 will not be affected by this configuration as they are not running as a virtual machine. +- To get to your `%UserProfile%` directory, in PowerShell, use `cd ~` to access your home directory (which is typically your user profile, `C:\Users\`) or you can open Windows File Explorer and enter `%UserProfile%` in the address bar. The directory path should look something like: `C:\Users\\.wslconfig`. -To unregister and uninstall a WSL distribution: +WSL will detect the existence of these files, read the contents, and automatically apply the configuration settings every time you launch WSL. If the file is missing or malformed (improper markup formatting), WSL will continue to launch as normal without the configuration settings applied. -`wsl --unregister ` -Unregisters the distribution from WSL so it can be reinstalled or cleaned up. **Caution:** Once unregistered, all data, settings, and software associated with that distribution will be permanently lost. Reinstalling from the store will install a clean copy of the distribution. - -For example: -`wsl --unregister Ubuntu` would remove Ubuntu from the distributions available in WSL. Running `wsl --list` will reveal that it is no longer listed. To reinstall, find the distribution in the Microsoft Store and select "Launch". - -## Run as a specific user - -`wsl -u `, `wsl --user ` - -Run WSL as the specified user. Please note that user must exist inside of the WSL distribution. - -## Change the default user for a distribution - -` config --default-user ` - -Change the default user that for your distribution log-in. The user has to already exist inside the distribution in order to become the default user. - -For example: -`ubuntu config --default-user johndoe` would change the default user for the Ubuntu distribution to the "johndoe" user. - -> [!NOTE] -> If you are having trouble figuring out the name of your distribution, use the command `wsl -l`. - -## Run a specific distribution - -`wsl -d `, `wsl --distribution ` - -Run a specified distribution of WSL, can be used to send commands to a specific distribution without having to change your default. - -## Configure settings with .wslconfig and wsl.conf - -You can configure options for your installed Linux distributions, such as automount options and network configuration, that will automatically be applied every time you launch WSL in two ways: - -- Globally for all installed distributions running in WSL 2 mode with a **.wslconfig** file stored in your `%UserProfile%` directory -- On a per-distribution basis with a **wsl.conf** file stored in the `/etc` directory of the distribution - -To get to your `%UserProfile%` directory, in PowerShell, use `cd ~` to access your home directory (which is typically your user profile, `C:\Users\`) or you can open Windows File Explorer and enter `%UserProfile%` in the address bar. The directory path for globally configuring WSL options will be `C:\Users\\.wslconfig`. - -To get to the `/etc` directory for an installed distribution, use the distribution's command line with `cd /` to access the root directory, then `ls` to list files or `explorer.exe .` to view in Windows File Explorer. The directory path for configuring WSL options on a per-distribution basis will be `/etc/wsl.conf`. - -WSL will detect the existence of these files and read the contents. If the file is missing or malformed (that is, improper markup formatting), WSL will continue to launch as normal. +[Check which version of WSL you are running.](./install.md#check-which-version-of-wsl-you-are-running) > [!NOTE] > Adjusting per-distribution settings with the wsl.conf file is only available in Windows Build 17093 and later. -## Per distribution configuration options with wsl.conf - -The `wsl.conf` sample file below demonstrates some of the configuration options available to add into your distributions: - -```console -# Enable extra metadata options by default -[automount] -enabled = true -root = /windir/ -options = "metadata,umask=22,fmask=11" -mountFsTab = false +### The 8 second rule -# Enable DNS – even though these are turned on by default, we'll specify here just to be explicit. -[network] -generateHosts = true -generateResolvConf = true -``` +You must wait until the subsystem running your Linux distribution completely stops running and restarts for configuration setting updates to appear. This typically takes about 8 seconds after closing ALL instances of the distribution shell. -When launching multiple Linux shells for the same distribution, you must wait until the Linux subsystem stops running, this can take approximately 8 seconds after closing the last instance of the distribution shell. If you launch a distribution (ie. Ubuntu), modify the wsl.conf file, close the distribution, and then re-launch it. You might assume that your changes to the wsl.conf file have immediately gone into effect. This is not currently the case as the subsystem could still be running. You must wait ~8 seconds for the subsystem to stop before relaunching in order to give enough time for your changes to be picked up. You can check to see whether your Linux distribution (shell) is still running after closing it by using PowerShell with the command: `wsl --list --running`. If no distributions are running, you will receive the response: "There are no running distributions." You can now restart the distribution to see your wsl.conf updates applied. +If you launch a distribution (ie. Ubuntu), modify the configuration file, close the distribution, and then re-launch it. You might assume that your configuration changes have immediately gone into effect. This is not currently the case as the subsystem could still be running. You must wait for the subsystem to stop before relaunching in order to give enough time for your changes to be picked up. You can check to see whether your Linux distribution (shell) is still running after closing it by using PowerShell with the command: `wsl --list --running`. If no distributions are running, you will receive the response: "There are no running distributions." You can now restart the distribution to see your configuration updates applied. -> [!TIP] -> `wsl --shutdown` is a fast path to restarting WSL 2 distributions, but it will shut down all running distributions, so use wisely. +The command `wsl --shutdown` is a fast path to restarting WSL 2 distributions, but it will shut down all running distributions, so use wisely. -### Options for wsl.conf +## Configuration settings for wsl.conf -In keeping with .ini conventions, keys are declared under a section. +The wsl.conf file configures settings on a per-distribution basis. *(For global configuration of WSL 2 distributions see [.wslconfig](#wslconfig)).* -WSL supports four sections: `automount`, `network`, `interop`, and `user`. +The wsl.conf file supports four sections: `automount`, `network`, `interop`, and `user`. *(Modeled after .ini file conventions, keys are declared under a section, like .gitconfig files.)* See [wsl.conf](#wslconf) for info on where to store the wsl.conf file. -#### automount +### Automount settings -Section: `[automount]` +Section label: `[automount]` | key | value | default | notes | |:-----------|:---------|:--------|:------| | enabled | boolean | true | `true` causes fixed drives (i.e `C:/` or `D:/`) to be automatically mounted with DrvFs under `/mnt`. `false` means drives won't be mounted automatically, but you could still mount them manually or via `fstab`. | | mountFsTab | boolean | true | `true` sets `/etc/fstab` to be processed on WSL start. /etc/fstab is a file where you can declare other filesystems, like an SMB share. Thus, you can mount these filesystems automatically in WSL on start up. | -| root| String | `/mnt/` | Sets the directory where fixed drives will be automatically mounted. For example, if you have a directory in WSL at `/windir/` and you specify that as the root, you would expect to see your fixed drives mounted at `/windir/c` | -| options | comma-separated list of values | empty string | This value is appended to the default DrvFs mount options string. **Only DrvFs-specific options can be specified.** Options that the mount binary would normally parse into a flag are not supported. If you want to explicitly specify those options, you must include every drive for which you want to do so in /etc/fstab. | +| root| string | `/mnt/` | Sets the directory where fixed drives will be automatically mounted. By default this is set to `/mnt/`, so your Windows file system C-drive is mounted to `/mnt/c/`. If you change `/mnt/` to `/windir/`, you should expect to see your fixed C-drive mounted to `/windir/c`.| +| options | comma-separated list of values, such as uid, gid, etc, see automount options below | empty string | The automount option values are listed below and are appended to the default DrvFs mount options string. **Only DrvFs-specific options can be specified.**| -By default, WSL sets the uid and gid to the value of the default user (in Ubuntu distro, the default user is created with uid=1000,gid=1000). If the user specifies a gid or uid option explicitly via this key, the associated value will be overwritten. Otherwise, the default value will always be appended. +The automount options are applied as the mount options for all automatically mounted drives. To change the options for a specific drive only, use the `/etc/fstab` file instead. Options that the mount binary would normally parse into a flag are not supported. If you want to explicitly specify those options, you must include every drive for which you want to do so in `/etc/fstab`. -**Note:** These options are applied as the mount options for all automatically mounted drives. To change the options for a specific drive only, use /etc/fstab instead. - -#### Mount options +#### Automount options Setting different mount options for Windows drives (DrvFs) can control how file permissions are calculated for Windows files. The following options are available: | Key | Description | Default | |:----|:----|:----| -|uid| The User ID used for the owner of all files | The default User ID of your WSL distro (On first installation this defaults to 1000) -|gid| The Group ID used for the owner of all files | The default group ID of your WSL distro (On first installation this defaults to 1000) +|uid| The User ID used for the owner of all files | The default User ID of your WSL distro (on first installation this defaults to 1000) +|gid| The Group ID used for the owner of all files | The default group ID of your WSL distro (on first installation this defaults to 1000) |umask | An octal mask of permissions to exclude for all files and directories | 000 |fmask | An octal mask of permissions to exclude for all files | 000 |dmask | An octal mask of permissions to exclude for all directories | 000 |metadata | Whether metadata is added to Windows files to support Linux system permissions | disabled |case | Determines directories treated as case sensitive and whether new directories created with WSL will have the flag set. See [case sensitivity](./case-sensitivity.md) for a detailed explanation of the options. | `off` +By default, WSL sets the uid and gid to the value of the default user. For example, in Ubuntu, the default user is uid=1000, gid=1000. If this value is used to specify a different gid or uid option, the default user value will be overwritten. Otherwise, the default value will always be appended. + +User file-creation mode mask (umask) sets permission for newly created files. The default is 022, only you can write data but anyone can read data. Values can be changed to reflect different permission settings. For example, `umask=077` changes permission to be completely private, no other user can read or write data. To further specify permission, fmask (files) and dmask (directories) can also be used. + > [!NOTE] > The permission masks are put through a logical OR operation before being applied to files or directories. -#### network +### Network settings Section label: `[network]` | key | value | default | notes| |:----|:----|:----|:----| | generateHosts | boolean | `true` | `true` sets WSL to generate `/etc/hosts`. The `hosts` file contains a static map of hostnames corresponding IP address. | -| generateResolvConf | boolean | `true` | `true` set WSL to generate `/etc/resolv.conf`. The `resolv.conf` contains a DNS list that are capable of resolving a given hostname to its IP address. | +| generateResolvConf | boolean | `true` | `true` set WSL to generate `/etc/resolv.conf`. The `resolv.conf` contains a DNS list that are capable of resolving a given hostname to its IP address. | -#### interop +### Interop settings Section label: `[interop]` @@ -161,7 +110,7 @@ These options are available in Insider Build 17713 and later. | enabled | boolean | `true` | Setting this key will determine whether WSL will support launching Windows processes. | | appendWindowsPath | boolean | `true` | Setting this key will determine whether WSL will add Windows path elements to the $PATH environment variable. | -#### user +### User settings Section label: `[user]` @@ -171,39 +120,72 @@ These options are available in Build 18980 and later. |:----|:----|:----|:----| | default | string | The initial username created on first run | Setting this key specifies which user to run as when first starting a WSL session. | -#### User preview options - -These options are only available in the latest preview builds if you are on the latest builds of the [Windows Insiders program](https://insider.windows.com/getting-started). +### Boot settings -##### boot +The Boot setting is only available on Windows 11. Section label: `[boot]` | key | value | default | notes| |:----|:----|:----|:----| -| command | string | "" | A string of the command that you would like to run when the WSL instance starts. This command is run as the root user. e.g: `service docker start` | +| command | string | "" | A string of the command that you would like to run when the WSL instance starts. This command is run as the root user. e.g: `service docker start` Only available for Windows 11.| -## Global configuration options with .wslconfig + -```console -[wsl2] -kernel=C:\\temp\\myCustomKernel -memory=4GB # Limits VM memory in WSL 2 to 4 GB -processors=2 # Makes the WSL 2 VM use two virtual processors +### Example wsl.conf file + +The `wsl.conf` sample file below demonstrates some of the configuration options available. In this example, the distribution is Ubuntu-20.04 and the file path is `\\wsl.localhost\Ubuntu-20.04\etc\wsl.conf`. + +```bash +# Automatically mount Windows drive when the distribution is launched +[automount] + +# Set to true will automount fixed drives (C:/ or D:/) with DrvFs under the root directory set above. Set to false means drives won't be mounted automatically, but need to be mounted manually or with fstab. +enabled = true + +# Sets the directory where fixed drives will be automatically mounted. This example changes the mount location, so your C-drive would be /c, rather than the default /mnt/c. +root = / + +# DrvFs-specific options can be specified. +options = "metadata,uid=1003,gid=1003,umask=077,fmask=11,case=off" + +# Sets the `/etc/fstab` file to be processed when a WSL distribution is launched. +mountFsTab = true + +# Network host settings that enable the DNS server used by WSL 2. This example changes the hostname, sets generateHosts to false, preventing WSL from the default behavior of auto-generating /etc/hosts, and sets generateResolvConf to false, preventing WSL from auto-generating /etc/resolv.conf, so that you can create your own (ie. nameserver 1.1.1.1). +[network] +hostname = DemoHost +generateHosts = false +generateResolvConf = false + +# Set whether WSL supports interop process like launching Windows apps and adding path variables. Setting these to false will block the launch of Windows processes and block adding $PATH environment variables. +[interop] +enabled = false +appendWindowsPath = false + +# Set the user when launching a distribution with WSL. +[user] +default = DemoUser + +# Set a command to run when a new WSL instance launches. This example starts the Docker container service. +[boot] +command = service docker start ``` -> [!NOTE] -> Global configuration options with `.wslconfig` in only available for distributions running as WSL 2 in Windows Build 19041 and later. Keep in mind you may need to run `wsl --shutdown` to shut down the WSL 2 VM and then restart your WSL instance for these changes to take affect. +## Configuration setting for .wslconfig -This file can contain the following options: +The .wslconfig file configures settings globally for all Linux distributions running with WSL 2. *(For per-distribution configuration see [wsl.conf](#wslconf)).* -### Options for .wslconfig +See [.wslconfig](#wslconfig) for info on where to store the .wslconfig file. -Section label: `[wsl2]` +> [!NOTE] +> Global configuration options with `.wslconfig` is only available for distributions running as WSL 2 in Windows Build 19041 and later. Keep in mind you may need to run `wsl --shutdown` to shut down the WSL 2 VM and then restart your WSL instance for these changes to take affect. -These settings affect the VM that powers any WSL 2 distribution. +This file can contain the following options that affect the VM that powers any WSL 2 distribution: + +Section label: `[wsl2]` | key | value | default | notes| |:----|:----|:----|:----| @@ -212,20 +194,62 @@ These settings affect the VM that powers any WSL 2 distribution. | processors | number | The same number of processors on Windows | How many processors to assign to the WSL 2 VM. | | localhostForwarding | boolean | `true` | Boolean specifying if ports bound to wildcard or localhost in the WSL 2 VM should be connectable from the host via `localhost:port`. | | kernelCommandLine | string | Blank | Additional kernel command line arguments. | -| swap | size | 25% of memory size on Windows rounded up to the nearest GB | How much swap space to add to the WSL 2 VM, 0 for no swap file. | +| swap | size | 25% of memory size on Windows rounded up to the nearest GB | How much swap space to add to the WSL 2 VM, 0 for no swap file. Swap storage is disk-based RAM used when memory demand exceeds limit on hardware device. | | swapFile | string | `%USERPROFILE%\AppData\Local\Temp\swap.vhdx` | An absolute Windows path to the swap virtual hard disk. | +| pageReporting | boolean | `true` | Default `true` setting enables Windows to reclaim unused memory allocated to WSL 2 virtual machine. | +| guiApplications | boolean* | `true` | Boolean to turn on or off support for GUI applications ([WSLg](https://github.com/microsoft/wslg)) in WSL. Only available for Windows 11.| +| debugConsole | boolean* | `false` | Boolean to turn on an output console Window that shows the contents of `dmesg` upon start of a WSL 2 distro instance. Only available for Windows 11.| +| nestedVirtualization | boolean* | `true` | Boolean to turn on or off nested virtualization, enabling other nested VMs to run inside WSL 2. Only available for Windows 11.| +| vmIdleTimeout | number* | `60000` | The number of milliseconds that a VM is idle, before it is shut down. Only available for Windows 11.| Entries with the `path` value must be Windows paths with escaped backslashes, e.g: `C:\\Temp\\myCustomKernel` Entries with the `size` value must be a size followed by a unit, for example `8GB` or `512MB`. -### WSL 2 setting preview options +Entries with an * after the value type are only available on Windows 11. + + + +## Example .wslconfig file + +The `.wslconfig` sample file below demonstrates some of the configuration options available. In this example, the file path is `C:\Users\\.wslconfig`. + +```bash +# Settings apply across all Linux distros running on WSL 2 +[wsl2] + +# Limits VM memory to use no more than 4 GB, this can be set as whole numbers using GB or MB +memory=4GB + +# Sets the VM to use two virtual processors +processors=2 + +# Specify a custom Linux kernel to use with your installed distros. The default kernel used can be found at https://github.com/microsoft/WSL2-Linux-Kernel +kernel=C:\\temp\\myCustomKernel + +# Sets additional kernel parameters, in this case enabling older Linux base images such as Centos 6 +kernelCommandLine = vsyscall=emulate + +# Sets amount of swap storage space to 8GB, default is 25% of available RAM +swap=8GB + +# Sets swapfile path location, default is %USERPROFILE%\AppData\Local\Temp\swap.vhdx +swapfile=C:\\temp\\wsl-swap.vhdx + +# Disable page reporting so WSL retains all allocated memory claimed from Windows and releases none back when free +pageReporting=false + +# Turn off default connection to bind WSL 2 localhost to Windows localhost +localhostforwarding=true + +# Disables nested virtualization +nestedVirtualization=false + +# Turns on output console showing contents of dmesg when opening a WSL 2 distro for debugging +debugConsole=true +```