├── .gitattributes ├── .github ├── ISSUE_TEMPLATE │ ├── config.yml │ ├── doc-issue.yml │ └── docs-issue.yaml ├── policies │ └── resourceManagement.yml └── workflows │ └── similarissues.yml ├── .gitignore ├── .openpublishing.publish.config.json ├── .openpublishing.redirection.json ├── LICENSE ├── LICENSE-CODE ├── README.md ├── ThirdPartyNotices └── WSL ├── about.md ├── basic-commands.md ├── breadcrumb └── toc.yml ├── build-custom-distro.md ├── case-sensitivity.md ├── compare-versions.md ├── connect-usb.md ├── disk-space.md ├── docfx.json ├── enterprise.md ├── faq.yml ├── file-permissions.md ├── filesystems.md ├── index.md ├── install-manual.md ├── install-on-server.md ├── install.md ├── intune.md ├── kernel-release-notes.md ├── media ├── UbuntuInstall.png ├── UbuntuStore.png ├── WindowsServer.png ├── appstorage-11.png ├── appstorage.png ├── bash.png ├── distro.png ├── docker-dashboard.png ├── docker-extension.png ├── docker-extension2.png ├── docker-extension3.png ├── docker-extension4.png ├── docker-running.png ├── docker-starting.png ├── firewallrulemerging.png ├── ghost_adapter_1.png ├── ghost_adapter_2.png ├── ghost_adapter_3.png ├── git-versions.gif ├── gpu-acceleration.gif ├── localappdata.png ├── ls.png ├── mongodb.png ├── new-user.png ├── ntfs-properties.png ├── run-any-distro-customuser.png ├── run-any-distro-import.png ├── run-any-distro-tarfile.png ├── server-appx-expand.png ├── store.png ├── system.png ├── systemd-enable.png ├── terminal.png ├── troubleshoot-vitualdisk-compress.png ├── troubleshooting-virtualdisk-compress.png ├── ubuntu-logo112.png ├── vs-target-system.png ├── vscode-remote-command-palette.png ├── vscode-remote-indicator.png ├── vscode-remote-wsl-extensions.png ├── vscode-run-config.png ├── vscode-running-in-container.png ├── windows-defender-firewall-settings.png ├── windows-file-explorer.png ├── windowsFeatures.png ├── wsl-architecture.png ├── wsl-gui-apps.png ├── wsl-gui-screenshot.png ├── wsl-icon.svg ├── wsl-install.png ├── wsl-open-vs-code.gif ├── wsl-opensource.png ├── wsl2-network-l2w.png ├── wsl2-network-w2l.jpg ├── wslmountsimple.png └── wslmountvhd.png ├── networking.md ├── opensource.md ├── release-notes.md ├── setup └── environment.md ├── store-release-notes.md ├── systemd.md ├── toc.yml ├── troubleshooting.md ├── tutorials ├── gpu-compute.md ├── gui-apps.md ├── linux.md ├── wsl-containers.md ├── wsl-database.md ├── wsl-git.md └── wsl-vscode.md ├── use-custom-distro.md ├── wsl-config.md ├── wsl-plugins.md └── wsl2-mount-disk.md /.gitattributes: -------------------------------------------------------------------------------- 1 | # Set the default behavior, in case people don't have core.autocrlf set. 2 | * text=auto 3 | 4 | # Explicitly declare text files you want to always be normalized and converted 5 | # to native line endings on checkout. 6 | *.c text 7 | *.h text 8 | 9 | # Declare files that will always have CRLF line endings on checkout. 10 | *.sln text eol=crlf 11 | 12 | # Denote all files that are truly binary and should not be modified. 13 | *.png binary 14 | *.jpg binary -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | blank_issues_enabled: false 2 | contact_links: 3 | - name: Report issues related to WSL 4 | url: https://github.com/microsoft/wsl/issues 5 | about: WSL product repo (for reporting WSL issues, bugs, or feature requests) 6 | - name: Report issues related to WSL GUI apps 7 | url: https://github.com/microsoft/wslg/issues 8 | about: WSLg repo (for reporting issues related to WSL GUI apps) 9 | - name: Report issues related to the Windows Terminal shell 10 | url: https://github.com/microsoft/terminal/issues 11 | about: Windows Terminal repo (for reporting issues related to the Terminal shell) 12 | - name: Report issues related to the Console 13 | url: https://github.com/MicrosoftDocs/Console-Docs/issues 14 | about: Windows Console repo (For reporting issues with CMD) 15 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/doc-issue.yml: -------------------------------------------------------------------------------- 1 | name: Post a documentation issue 2 | title: Contribute Feedback 3 | description: >- 4 | Post an issue specific to WSL documentation. 5 | labels: 6 | - "needs-triage" 7 | body: 8 | - type: markdown 9 | attributes: 10 | value: "## Enter your feedback" 11 | - type: markdown 12 | attributes: 13 | value: Select the issue type, and describe the issue in the text box below. Add as much detail as needed to help us resolve the issue. 14 | - type: dropdown 15 | id: issue-type 16 | attributes: 17 | label: Type of issue 18 | options: 19 | - Typo 20 | - Code doesn't work 21 | - Missing information 22 | - Outdated article 23 | - Other (describe below) 24 | validations: 25 | required: true 26 | - type: textarea 27 | id: userfeedback 28 | validations: 29 | required: true 30 | attributes: 31 | label: Feedback 32 | description: Provide details that will add context on what should be updated in the documentation. Additional details not needed for typos, grammar, formatting, etc. For technical or factual errors, please include code snippets and output to show how the documentation is incorrect. 33 | - type: markdown 34 | attributes: 35 | value: "## Article information" 36 | - type: markdown 37 | attributes: 38 | value: "*Don't modify the following fields*. They are automatically filled in for you. Doing so will disconnect your issue from the affected article. *Don't edit them*." 39 | - type: input 40 | id: pageUrl 41 | validations: 42 | required: true 43 | attributes: 44 | label: Page URL 45 | - type: input 46 | id: contentSourceUrl 47 | validations: 48 | required: true 49 | attributes: 50 | label: Content source URL 51 | - type: input 52 | id: author 53 | validations: 54 | required: true 55 | attributes: 56 | label: Author 57 | description: GitHub Id of the author 58 | - type: input 59 | id: documentVersionIndependentId 60 | validations: 61 | required: true 62 | attributes: 63 | label: Document Id 64 | - type: input 65 | id: platformId 66 | validations: 67 | required: true 68 | attributes: 69 | label: Platform Id 70 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/docs-issue.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | name: WSL documentation issue 3 | description: Report an issue regarding the documentation of WSL 4 | body: 5 | - type: textarea 6 | attributes: 7 | label: Documentation Issue 8 | description: Please list out what errors you're seeing in the WSL documentation 9 | placeholder: Links to the relevant docs page and a description of what the problem is with its content. 10 | validations: 11 | required: true 12 | 13 | - type: textarea 14 | attributes: 15 | label: Link to documentation page 16 | description: Please list out what errors you're seeing in the WSL documentation 17 | placeholder: Link to the doc page where you're seeing this error 18 | validations: 19 | required: true 20 | 21 | - type: textarea 22 | attributes: 23 | label: Suggested Improvements 24 | description: Please list what actionable changes you would like to see to the docs to improve this 25 | validations: 26 | required: false 27 | -------------------------------------------------------------------------------- /.github/policies/resourceManagement.yml: -------------------------------------------------------------------------------- 1 | id: 2 | name: GitOps.PullRequestIssueManagement 3 | description: GitOps.PullRequestIssueManagement primitive 4 | owner: 5 | resource: repository 6 | disabled: false 7 | where: 8 | configuration: 9 | resourceManagementConfiguration: 10 | scheduledSearches: 11 | - description: 12 | frequencies: 13 | - hourly: 14 | hour: 3 15 | filters: 16 | - isIssue 17 | - isOpen 18 | - hasLabel: 19 | label: needs-author-feedback 20 | - noActivitySince: 21 | days: 7 22 | actions: 23 | - closeIssue 24 | eventResponderTasks: 25 | - if: 26 | - payloadType: Issue_Comment 27 | - isAction: 28 | action: Created 29 | - isActivitySender: 30 | issueAuthor: True 31 | - hasLabel: 32 | label: needs-author-feedback 33 | then: 34 | - removeLabel: 35 | label: needs-author-feedback 36 | - removeLabel: 37 | label: no-recent-activity 38 | description: 39 | - if: 40 | - payloadType: Issue_Comment 41 | - isAction: 42 | action: Created 43 | - or: 44 | - isActivitySender: 45 | user: craigloewen-msft 46 | issueAuthor: False 47 | - isActivitySender: 48 | user: therealkenc 49 | issueAuthor: False 50 | - isActivitySender: 51 | user: benhillis 52 | issueAuthor: False 53 | - hasLabel: 54 | label: needs-attention 55 | then: 56 | - removeLabel: 57 | label: needs-attention 58 | description: 59 | - if: 60 | - payloadType: Issue_Comment 61 | - commentContains: 62 | pattern: '\/dupe?(\s+of)?\s+\#[\d]+' 63 | isRegex: True 64 | - or: 65 | - activitySenderHasPermission: 66 | permission: Admin 67 | - activitySenderHasPermission: 68 | permission: Write 69 | then: 70 | - addReply: 71 | reply: >- 72 | Hi! We've identified this issue as a duplicate of another one that already exists in this repository. This specific instance is being closed in favor of tracking the concern over on the referenced thread. 73 | 74 | 75 | Thanks for your report! 76 | - closeIssue 77 | - addLabel: 78 | label: duplicate 79 | description: 80 | - if: 81 | - payloadType: Issue_Comment 82 | - commentContains: 83 | pattern: '\/product' 84 | isRegex: True 85 | - or: 86 | - activitySenderHasPermission: 87 | permission: Admin 88 | - activitySenderHasAssociation: 89 | association: Member 90 | - activitySenderHasPermission: 91 | permission: Write 92 | then: 93 | - addReply: 94 | reply: >- 95 | Hi! This issue is a technical issue related to WSL. This repo is just for managing issues relating specifically to the WSL docs pages. If you're still experiencing this issue please file it at https://github.com/microsoft/WSL , the relevant info there will help us give you an actionable solution. 96 | 97 | 98 | Thank you for filing! 99 | - closeIssue 100 | description: 101 | onFailure: 102 | onSuccess: 103 | -------------------------------------------------------------------------------- /.github/workflows/similarissues.yml: -------------------------------------------------------------------------------- 1 | name: GitGudSimilarIssues comments 2 | 3 | on: 4 | issues: 5 | types: [opened] 6 | 7 | jobs: 8 | getsimilarissues: 9 | runs-on: ubuntu-latest 10 | outputs: 11 | message: ${{ steps.getbody.outputs.message }} 12 | steps: 13 | - uses: actions/checkout@v2 14 | - id: getbody 15 | uses: craigloewen-msft/GitGudSimilarIssues@main 16 | with: 17 | issuetitle: ${{ github.event.issue.title }} 18 | repo: ${{ github.repository }} 19 | similaritytolerance: "0.8" 20 | add-comment: 21 | needs: getsimilarissues 22 | runs-on: ubuntu-latest 23 | permissions: 24 | issues: write 25 | steps: 26 | - name: Add comment 27 | run: gh issue comment "$NUMBER" --repo "$REPO" --body "$BODY" 28 | env: 29 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 30 | NUMBER: ${{ github.event.issue.number }} 31 | REPO: ${{ github.repository }} 32 | BODY: ${{ needs.getsimilarissues.outputs.message }} -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | log/ 2 | xhtml/ 3 | packages/ 4 | obj/ 5 | _site/ 6 | Tools/NuGet/ 7 | .optemp/ 8 | 9 | .openpublishing.build.mdproj 10 | .openpublishing.buildcore.ps1 11 | packages.config 12 | .vscode/settings.json 13 | -------------------------------------------------------------------------------- /.openpublishing.publish.config.json: -------------------------------------------------------------------------------- 1 | { 2 | "docsets_to_publish": [ 3 | { 4 | "docset_name": "wsl", 5 | "build_source_folder": "WSL", 6 | "build_output_subfolder": "wsl", 7 | "locale": "en-us", 8 | "monikers": [], 9 | "moniker_ranges": [], 10 | "open_to_public_contributors": true, 11 | "type_mapping": { 12 | "Conceptual": "Content", 13 | "ManagedReference": "Content", 14 | "RestApi": "Content" 15 | }, 16 | "build_entry_point": "docs", 17 | "template_folder": "_themes" 18 | } 19 | ], 20 | "notification_subscribers": [ 21 | "mattwoj@microsoft.com" 22 | ], 23 | "sync_notification_subscribers": [], 24 | "branches_to_filter": [], 25 | "git_repository_url_open_to_public_contributors": "https://github.com/MicrosoftDocs/wsl", 26 | "git_repository_branch_open_to_public_contributors": "main", 27 | "skip_source_output_uploading": false, 28 | "need_preview_pull_request": true, 29 | "contribution_branch_mappings": {}, 30 | "dependent_repositories": [ 31 | { 32 | "path_to_root": "_themes", 33 | "url": "https://github.com/Microsoft/templates.docs.msft", 34 | "branch": "main", 35 | "branch_mapping": {} 36 | }, 37 | { 38 | "path_to_root": "_themes.pdf", 39 | "url": "https://github.com/Microsoft/templates.docs.msft.pdf", 40 | "branch": "main", 41 | "branch_mapping": {} 42 | } 43 | ], 44 | "branch_target_mapping": { 45 | "live": [ 46 | "Publish", 47 | "Intellisense", 48 | "Pdf" 49 | ] 50 | }, 51 | "need_generate_pdf_url_template": true, 52 | "targets": { 53 | "pdf": { 54 | "template_folder": "_themes.pdf" 55 | } 56 | }, 57 | "docs_build_engine": { 58 | "name": "docfx_v3" 59 | } 60 | } -------------------------------------------------------------------------------- /.openpublishing.redirection.json: -------------------------------------------------------------------------------- 1 | { 2 | "redirections": [ 3 | { 4 | "source_path": "wsl/release_notes.md", 5 | "redirect_url": "/windows/wsl/release-notes", 6 | "redirect_document_id": true 7 | }, 8 | { 9 | "source_path": "wsl/install_guide.md", 10 | "redirect_url": "/windows/wsl/install", 11 | "redirect_document_id": false 12 | }, 13 | { 14 | "source_path": "wsl/wsl2-about.md", 15 | "redirect_url": "/windows/wsl/compare-versions#whats-new-in-wsl-2", 16 | "redirect_document_id": false 17 | }, 18 | { 19 | "source_path": "wsl/wsl2-index.md", 20 | "redirect_url": "/windows/wsl/compare-versions#whats-new-in-wsl-2", 21 | "redirect_document_id": false 22 | }, 23 | { 24 | "source_path": "wsl/wsl2-install.md", 25 | "redirect_url": "/windows/wsl/install", 26 | "redirect_document_id": false 27 | }, 28 | { 29 | "source_path": "wsl/wsl2-kernel.md", 30 | "redirect_url": "/windows/wsl/install-manual#step-4---download-the-linux-kernel-update-package", 31 | "redirect_document_id": false 32 | }, 33 | { 34 | "source_path": "wsl/install-win10.md", 35 | "redirect_url": "/windows/wsl/install", 36 | "redirect_document_id": true 37 | }, 38 | { 39 | "source_path": "wsl/interop.md", 40 | "redirect_url": "/windows/wsl/filesystems", 41 | "redirect_document_id": false 42 | }, 43 | { 44 | "source_path": "wsl/reference.md", 45 | "redirect_url": "/windows/wsl/basic-commands", 46 | "redirect_document_id": false 47 | }, 48 | { 49 | "source_path": "wsl/manage.md", 50 | "redirect_url": "/windows/wsl/wsl-config", 51 | "redirect_document_id": false 52 | }, 53 | { 54 | "source_path": "wsl/wsl2-faq.md", 55 | "redirect_url": "/windows/wsl/faq", 56 | "redirect_document_id": false 57 | }, 58 | { 59 | "source_path": "wsl/user_support.md", 60 | "redirect_url": "/windows/wsl/setup/environment#set-up-your-linux-username-and-password", 61 | "redirect_document_id": false 62 | }, 63 | { 64 | "source_path": "wsl/user-support.md", 65 | "redirect_url": "/windows/wsl/setup/environment#set-up-your-linux-username-and-password", 66 | "redirect_document_id": false 67 | }, 68 | { 69 | "source_path": "wsl/vhd-size.md", 70 | "redirect_url": "/windows/wsl/disk-space", 71 | "redirect_document_id": false 72 | } 73 | ] 74 | } 75 | -------------------------------------------------------------------------------- /LICENSE-CODE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | Copyright (c) Microsoft Corporation 3 | 4 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 5 | associated documentation files (the "Software"), to deal in the Software without restriction, 6 | including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 7 | and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, 8 | subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice shall be included in all copies or substantial 11 | portions of the Software. 12 | 13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT 14 | NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 15 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 16 | WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 17 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Windows Subsystem for Linux (WSL) Documentation 2 | 3 | ## Issues 4 | If you find doc issues / errors or have an improvement you'd like to suggest, please file an issue and/or submit a pull-request - we greatly appreciate PR's in particular :) 5 | 6 | > **Note:** This repo's issue tracker is only for reporting issues with the WSL docs. 7 | > Other related issue repo's: 8 | > * WSL: https://github.com/Microsoft/WSL/ 9 | > * Windows Console: https://github.com/Microsoft/Terminal/ 10 | 11 | ## External Links 12 | 13 | [Rendered documentation website](https://learn.microsoft.com/windows/wsl/) 14 | 15 | [Release notes for WSL](https://learn.microsoft.com/windows/wsl/release-notes) 16 | 17 | ## Microsoft Open Source Code of Conduct 18 | 19 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). 20 | For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. 21 | 22 | Welcome to the markdown source for Microsoft's command-line shells and console documentation. 23 | 24 | ## License 25 | Distributed under the Creative Commons Attribution 4.0 International (CC BY 4.0) Public License. 26 | -------------------------------------------------------------------------------- /ThirdPartyNotices: -------------------------------------------------------------------------------- 1 | ##Legal Notices 2 | Microsoft and any contributors grant you a license to the Microsoft documentation and other content 3 | in this repository under the [Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/legalcode), 4 | see the [LICENSE](LICENSE) file, and grant you a license to any code in the repository under the [MIT License](https://opensource.org/licenses/MIT), see the 5 | [LICENSE-CODE](LICENSE-CODE) file. 6 | 7 | Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation 8 | may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. 9 | The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. You can find Microsoft general trademark guidelines at 10 | [Microsoft Trademark and Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks). 11 | 12 | For privacy information, see [privacy at Microsoft](https://privacy.microsoft.com/en-us/). 13 | 14 | Microsoft and any contributors reserve all others rights, whether under their respective copyrights, patents, 15 | or trademarks, whether by implication, estoppel or otherwise. 16 | -------------------------------------------------------------------------------- /WSL/about.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: What is Windows Subsystem for Linux 3 | description: Learn about the Windows Subsystem for Linux, including the different versions and ways you can use them. Microsoft Loves Linux. 4 | ms.date: 05/19/2025 5 | ms.topic: article 6 | --- 7 | 8 | # What is the Windows Subsystem for Linux? 9 | 10 | Windows Subsystem for Linux (WSL) is a feature of Windows that allows you to run a Linux environment on your Windows machine, without the need for a separate virtual machine or dual booting. WSL is designed to provide a seamless and productive experience for developers who want to use both Windows and Linux at the same time. 11 | 12 | - Use WSL to install and run various Linux distributions, such as Ubuntu, Debian, Kali, and more. [Install Linux distributions](./install.md) and receive automatic updates from the [Microsoft Store](./compare-versions.md#wsl-in-the-microsoft-store), [import Linux distributions not available in the Microsoft Store](./use-custom-distro.md), or [build your own custom Linux distribution](./build-custom-distro.md). 13 | - Store files in an isolated Linux file system, specific to the installed distribution. 14 | - Run command-line tools, such as BASH. 15 | - Run common BASH command-line tools such as `grep`, `sed`, `awk`, or other ELF-64 binaries. 16 | - Run Bash scripts and GNU/Linux command-line applications including: 17 | - Tools: vim, emacs, tmux 18 | - Languages: [NodeJS](/windows/nodejs/setup-on-wsl2), JavaScript, [Python](/windows/python/web-frameworks), Ruby, C/C++, C# & F#, Rust, Go, etc. 19 | - Services: SSHD, [MySQL](./tutorials/wsl-database.md), Apache, lighttpd, [MongoDB](./tutorials/wsl-database.md), [PostgreSQL](./tutorials/wsl-database.md). 20 | - Install additional software using your own GNU/Linux distribution package manager. 21 | - Invoke Windows applications using a Unix-like command-line shell. 22 | - Invoke GNU/Linux applications on Windows. 23 | - [Run GNU/Linux graphical applications](./tutorials/gui-apps.md) integrated directly to your Windows desktop 24 | - Use your device [GPU to accelerate Machine Learning workloads running on Linux.](./tutorials/gpu-compute.md) 25 | 26 | WSL is an Open Source tool with source code available for download and contributions: 27 | 28 | - [Learn more about WSL open source components](opensource.md) 29 | - WSL Open Source docs site: [wsl.dev](https://wsl.dev) 30 | - WSL repository on GitHub: [github.com/Microsoft/wsl](https://github.com/microsoft/WSL) 31 | 32 | Get started using WSL: 33 | 34 | > [!div class="nextstepaction"] 35 | > [Install WSL](install.md) 36 | 37 |
38 | 39 | > [!VIDEO https://www.youtube.com/embed/48k317kOxqg] 40 | 41 | ## What is WSL 2? 42 | 43 | WSL 2 is the default distro type when installing a Linux distribution. WSL 2 uses virtualization technology to run a Linux kernel inside of a lightweight utility virtual machine (VM). Linux distributions run as isolated containers inside of the WSL 2 managed VM. Linux distributions running via WSL 2 will share the same network namespace, device tree (other than `/dev/pts`), CPU/Kernel/Memory/Swap, `/init` binary, but have their own PID namespace, Mount namespace, User namespace, Cgroup namespace, and `init` process. 44 | 45 | WSL 2 **increases file system performance** and adds **full system call compatibility** in comparison to the WSL 1 architecture. Learn more about how [WSL 1 and WSL 2 compare](./compare-versions.md). 46 | 47 | Individual Linux distributions can be run with either the WSL 1 or WSL 2 architecture. Each distribution can be upgraded or downgraded at any time and you can run WSL 1 and WSL 2 distributions side by side. See the [Set WSL version command](/windows/wsl/basic-commands#set-default-wsl-version). 48 | 49 | > [!VIDEO https://www.youtube.com/embed/MrZolfGm8Zk] 50 | 51 | ## Microsoft Loves Linux 52 | 53 | Learn more about [Linux resources at Microsoft](/linux), including Microsoft tools that run on Linux, Linux training courses, Cloud Solution Architecture for Linux, and Microsoft + Linux news, events, and partnerships. **Microsoft Loves Linux!** 54 | -------------------------------------------------------------------------------- /WSL/breadcrumb/toc.yml: -------------------------------------------------------------------------------- 1 | - name: Windows 2 | tocHref: /windows/ 3 | topicHref: /windows/index 4 | items: 5 | - name: WSL 6 | tocHref: /windows/wsl/ 7 | topicHref: /windows/wsl/index 8 | -------------------------------------------------------------------------------- /WSL/case-sensitivity.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Case Sensitivity 3 | description: Learn how case sensitive file names are handled between Windows and Linux file systems, how to adjust these settings by directory with WSL, and how to troubleshoot issues. 4 | keywords: case sensitivity, wsl, windows, linux, ntfs, mount 5 | ms.date: 09/27/2021 6 | ms.topic: article 7 | --- 8 | 9 | # Adjust case sensitivity 10 | 11 | Case sensitivity determines whether uppercase (FOO.txt) and lowercase (foo.txt) letters are handled as distinct (case-sensitive) or equivalent (case-insensitive) in a file name or directory. 12 | 13 | - Case-sensitive: FOO.txt ≠ foo.txt ≠ Foo.txt 14 | - Case-insensitive: FOO.txt = foo.txt = Foo.txt 15 | 16 | ## Differences between Windows and Linux case sensitivity 17 | 18 | When working with both Linux and Windows files and directories, you may need to adjust how case sensitivity is handled. 19 | 20 | Standard behavior: 21 | 22 | - Windows file system treats file and directory names as case-insensitive. FOO.txt and foo.txt will be treated as equivalent files. 23 | - Linux file system treats file and directory names as case-sensitive. FOO.txt and foo.txt will be treated as distinct files. 24 | 25 | The Windows file system supports setting case sensitivity with attribute flags per directory. While the standard behavior is to be case-insensitive, you can assign an attribute flag to make a directory case sensitive, so that it will recognize Linux files and folders that may differ only by case. 26 | 27 | This may be especially true when mounting drives to the Windows Subsystem for Linux (WSL) file system. When working in the WSL file system, you are running Linux, thus files and directories are treated as case-sensitive by default. 28 | 29 | > [!NOTE] 30 | > In the past, if you had files whose name differed only by case, these files could not be accessed by Windows, because Windows applications treat the file system as case insensitive and cannot distinguish between files whose names only differ in case. While Windows File Explorer will show both files, only one will open regardless of which you select. 31 | 32 | ## Change the case sensitivity of files and directories 33 | 34 | The following steps explain how to change a directory on the Windows file system so that it is case-sensitive and will recognize files and folders that differ only by case. 35 | 36 | > [!WARNING] 37 | > Some Windows applications, using the assumption that the file system is case insensitive, don’t use the correct case to refer to files. For example, it’s not uncommon for applications to transform filenames to use all upper or lower case. In directories marked as case sensitive, this means that these applications can no longer access the files. Additionally, if Windows applications create new directories in a directory tree where you are using case sensitive files, these directories are not case sensitive. This can make it difficult to work with Windows tools in case sensitive directories, so exercise caution when changing Windows file system case-sensitivity settings. 38 | 39 | ### Inspect current case sensitivity 40 | 41 | To check if a directory is case sensitive in the Windows filesystem, run the command: 42 | 43 | ```powershell 44 | fsutil.exe file queryCaseSensitiveInfo 45 | ``` 46 | 47 | Replace `` with your file path. For a directory in the Windows (NTFS) file system, the `` will look like: `C:\Users\user1\case-test` or if you are already in the `user1` directory, you could just run: `fsutil.exe file setCaseSensitiveInfo case-test` 48 | 49 | ### Modify case sensitivity 50 | 51 | Support for per-directory case sensitivity began in Windows 10, build 17107. In Windows 10, build 17692, support was updated to include inspecting and modifying the case sensitivity flag for a directory from inside WSL. Case sensitivity is exposed using an extended attribute named `system.wsl_case_sensitive`. The value of this attribute will be 0 for case insensitive directories, and 1 for case sensitive directories. 52 | 53 | Changing the case-sensitivity of a directory requires that you run **elevated permissions** (run as Administrator). Changing the case-sensitivity flag also requires “Write attributes”, “Create files”, “Create folders” and “Delete subfolders and files” permissions on the directory. [See the troubleshooting section for more about this](#error-access-denied). 54 | 55 | To change a directory in the Windows file system so that it is case-sensitive (FOO ≠ foo), run PowerShell as Administrator and use the command: 56 | 57 | ```powershell 58 | fsutil.exe file setCaseSensitiveInfo enable 59 | ``` 60 | 61 | To change a directory in the Windows file system back to the case-insensitive default (FOO = foo), run PowerShell as Administrator and use the command: 62 | 63 | ```powershell 64 | fsutil.exe file setCaseSensitiveInfo disable 65 | ``` 66 | 67 | A directory must be empty in order to change the case sensitivity flag attribute on that directory. You cannot disable the case sensitivity flag on a directory containing folders/files whose names differ on only by case. 68 | 69 | ### Case sensitivity inheritance 70 | 71 | When creating new directories, those directories will inherit the case sensitivity from its parent directory. 72 | 73 | > [!WARNING] 74 | > There is an exception to this inheritance policy when running in WSL 1 mode. When a distribution is running in WSL 1 mode, the per-directory case sensitivity flag is not inherited; directories created in a case sensitive directory are not automatically case sensitive themselves. You must explicitly mark each directory as case sensitive 75 | 76 | ## Case sensitivity options for mounting a drive in WSL configuration file 77 | 78 | Case sensitivity can be managed when mounting a drive on the Windows Subsystem for Linux using the WSL config file. Each Linux distribution that you have installed can have it's own WSL config file, called `/etc/wsl.conf`. For more information about how to mount a drive, see [Get started mounting a Linux disk in WSL 2](./wsl2-mount-disk.md). 79 | 80 | To configure the case sensitivity option in the `wsl.conf` file when mounting a drive: 81 | 82 | 1. Open the Linux distribution you will be using (ie. Ubuntu). 83 | 2. Change directories up until you see the `etc` folder (this may require you to `cd ..` up from the `home` directory). 84 | 3. List the files in the `etc` directory to see if a `wsl.conf` file already exists (use the `ls` command, or `explorer.exe .` to view the directory with Windows File Explorer). 85 | 4. If the `wsl.conf` file does not already exist, you can create it using: `sudo touch wsl.conf` or by running `sudo nano /etc/wsl.conf`, which will create the file upon saving from the Nano editor. 86 | 5. The following options are available for you to add into your `wsl.conf` file: 87 | 88 | **Default setting: `dir` for enabling case sensitivity per directory.** 89 | 90 | ```bash 91 | [automount] 92 | options = case = dir 93 | ``` 94 | 95 | **Case sensitivity unavailable (all directories on mounted NTFS drives will be case insensitive): `off`** 96 | 97 | ```bash 98 | [automount] 99 | options = case = off 100 | ``` 101 | 102 | **Treat all directories on the (NTFS) drive as case sensitive: `force`** 103 | 104 | ```bash 105 | [automount] 106 | options = case = force 107 | ``` 108 | 109 | This option is only supported for mounting drives on Linux distributions running as WSL 1 and may require a registration key. To add a registration key, you can use this command from an elevated (admin) command prompt: `reg.exe add HKLM\SYSTEM\CurrentControlSet\Services\lxss /v DrvFsAllowForceCaseSensitivity /t REG_DWORD /d 1`. 110 | 111 | You will need to restart WSL after making any changes to the `wsl.conf` file in order for those changes to take effect. You can restart WSL using the command: `wsl --shutdown` 112 | 113 | > [!TIP] 114 | > To mount a drive (which uses the DrvFs filesystem plugin to make the disk available under /mnt, such as /mnt/c, /mnt/d, etc) with a specific case sensitivity setting for ALL drives, use `/etc/wsl.conf` as described above. To set the default mount options for one specific drive, use the [`/etc/fstab` file](http://manpages.ubuntu.com/manpages/xenial/man5/fstab.5.html) to specify these options. 115 | > For more WSL configuration options, see [Configure per distro launch settings with wslconf](/windows/wsl/wsl-config#configure-settings-with-wslconfig-and-wslconf). 116 | 117 | ### Changing the case sensitivity on a drive mounted to a WSL distribution 118 | 119 | NTFS-formatted drives mounted to a WSL distribution will be case-insensitive by default. To change the case sensitivity for a directory on a drive mounted to a WSL distribution (ie. Ubuntu), follow the same steps as listed above for the Windows file system. (EXT4 drives will be case-sensitive by default). 120 | 121 | To enable case-sensitivity on a directory (FOO ≠ foo), use the command: 122 | 123 | ```bash 124 | fsutil.exe file setCaseSensitiveInfo enable 125 | ``` 126 | 127 | To disable case-sensitivity on a directory and return to the case-insensitive default (FOO = foo), use the command: 128 | 129 | ```bash 130 | fsutil.exe file setCaseSensitiveInfo disable 131 | ``` 132 | 133 | > [!NOTE] 134 | > If you change the case sensitive flag on an existing directory for a mounted drive while WSL is running, ensure WSL has no references to that directory or else the change will not be effective. This means the directory must not be open by any WSL processes, including using the directory (or its descendants) as the current working directory. 135 | 136 | ## Configure case sensitivity with Git 137 | 138 | The Git version control system also has a configuration setting that can be used to adjust case sensitivity for the files you are working with. If you are using Git, you may want to adjust the [`git config core.ignorecase`](https://git-scm.com/docs/git-config/#Documentation/git-config.txt-coreignoreCase) setting. 139 | 140 | To set Git to be case-sensitive (FOO.txt ≠ foo.txt), enter: 141 | 142 | `git config core.ignorecase false` 143 | 144 | To set Git to be case-insensitive (FOO.txt = foo.txt), enter: 145 | 146 | `git config core.ignorecase true` 147 | 148 | Setting this option to false on a case-insensitive file system may lead to confusing errors, false conflicts, or duplicate files. 149 | 150 | For more information, see the [Git Config documentation](https://git-scm.com/docs/git-config/). 151 | 152 | ## Troubleshooting 153 | 154 | ### My directory has files that are mixed case and require case sensitivity but Windows FS tools will not recognize these files 155 | 156 | To use Windows file system tools to work on a Linux directory that contains mixed case files, you will need to create a brand new directory and set it to be case-sensitive, then copy the files into that directory (using git clone or untar). The files will remain mixed case. (Note that if you have already tried moving the files to a case-insensitive directory and there were conflicts, there were likely some files that were overwritten and will no longer be available.) 157 | 158 | ### Error: The directory is not empty 159 | 160 | You cannot change the case sensitivity setting on a directory that contains other files or directories. Try creating a new directory, changing the setting, then copying your mixed-case files into it. 161 | 162 | ### Error: Access denied 163 | 164 | Ensure that you have the “Write attributes”, “Create files”, “Create folders” and “Delete subfolders and files” permissions on the directory required for changing case-sensitivity. To check these settings, open the directory in Windows File Explorer (from command line, use the command: `explorer.exe .`). Right-click the directory and select **Properties** to open the Document Properties window, then select **Edit** to view or change permissions for the directory. 165 | 166 | ![Properties windows to view or change permissions on NTFS directories](./media/ntfs-properties.png) 167 | 168 | ### Error: A local NTFS volume is required for this operation 169 | 170 | The case sensitivity attribute can only be set on directories within an NTFS-formatted file system. Directories in the WSL (Linux) file system are case sensitive by default (and cannot be set to be case insensitive using the fsutil.exe tool). 171 | 172 | ## Additional resources 173 | 174 | - [DevBlog: Per-directory case sensitivity and WSL](https://devblogs.microsoft.com/commandline/per-directory-case-sensitivity-and-wsl/) 175 | - [DevBlog: Improved per-directory case sensitivity support in WSL](https://devblogs.microsoft.com/commandline/improved-per-directory-case-sensitivity-support-in-wsl/) 176 | -------------------------------------------------------------------------------- /WSL/compare-versions.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Comparing WSL Versions 3 | 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. 4 | ms.date: 11/19/2024 5 | ms.topic: conceptual 6 | ms.custom: seo-windows-dev 7 | --- 8 | 9 | # Comparing WSL Versions 10 | 11 | Learn more about different WSL versions, including why WSL 2 is now the default and the specific scenarios or exceptions that may warrant switching your installed Linux distribution to the earlier WSL 1 architecture. 12 | 13 | ## Comparing WSL 1 and WSL 2 14 | 15 | 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. WSL 2 is the current default version when installing a Linux distribution and uses the latest and greatest in virtualization technology to run a Linux kernel inside of a lightweight utility virtual machine (VM). WSL2 runs Linux distributions as isolated containers inside the managed VM. If your distribution is currently running WSL 1 and you want to update to WSL 2, see [update from WSL 1 to WSL 2](./install.md#upgrade-version-from-wsl-1-to-wsl-2). 16 | 17 | ### Comparing features 18 | 19 | Feature | WSL 1 | WSL 2 20 | --- | --- | --- 21 | Integration between Windows and Linux| ✅|✅ 22 | Fast boot times| ✅ | ✅ 23 | Small resource foot print compared to traditional Virtual Machines| ✅ |✅ 24 | Runs with current versions of VMware and VirtualBox| ✅ | ❌ 25 | Managed VM| ❌ | ✅ 26 | Full Linux Kernel| ❌ |✅ 27 | Full system call compatibility| ❌ | ✅ 28 | Performance across OS file systems| ✅ | ❌ 29 | systemd support| ❌ | ✅ 30 | IPv6 support| ✅ | ✅ 31 | 32 | 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. 33 | 34 | WSL 2 is only available in Windows 11 or Windows 10, Version 1903, Build 18362 or later. 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 14393, WSL is not supported at all. 35 | 36 | For more info on the latest WSL 2 updates, see the [Windows Command Line blog](https://devblogs.microsoft.com/commandline/), including [Systemd support is now available in WSL](https://devblogs.microsoft.com/commandline/systemd-support-is-now-available-in-wsl/) and [WSL September 2023 update](https://devblogs.microsoft.com/commandline/windows-subsystem-for-linux-september-2023-update/) for more info on IPv6 support. 37 | 38 | > [!NOTE] 39 | > WSL 2 will work with [VMware 15.5.5+](https://blogs.vmware.com/workstation/2020/05/vmware-workstation-now-supports-hyper-v-mode.html) and although [VirtualBox 6+](https://www.virtualbox.org/wiki/Changelog-6.0) states that there is WSL support, there are still significant challenges that make it unsupported. Learn more in our [FAQs.](./faq.yml#will-i-be-able-to-run-wsl-2-and-other-3rd-party-virtualization-tools-such-as-vmware--or-virtualbox-) 40 | 41 | ## What's new in WSL 2 42 | 43 | WSL 2 is a major overhaul of the underlying architecture and uses virtualization technology and a Linux kernel to enable new features. The primary goals of this update are to increase file system performance and add full system call compatibility. 44 | 45 | - [WSL 2 system requirements](./install-manual.md#step-2---check-requirements-for-running-wsl-2) 46 | - [Set your Linux distribution version from WSL 1 to WSL 2](./basic-commands.md#set-wsl-version-to-1-or-2) 47 | - [Frequently Asked Questions about WSL 2](./faq.yml) 48 | 49 | ### WSL 2 architecture 50 | 51 | A traditional VM experience can be slow to boot up, is isolated, consumes a lot of resources, and requires your time to manage it. WSL 2 does not have these attributes. 52 | 53 | WSL 2 provides the benefits of WSL 1, including seamless integration between Windows and Linux, fast boot times, a small resource footprint, and requires no VM configuration or management. While WSL 2 does use a VM, it is managed and run behind the scenes, leaving you with the same user experience as WSL 1. 54 | 55 | ### Full Linux kernel 56 | 57 | The Linux kernel in WSL 2 is built by Microsoft from the latest stable branch, based on the source available at [kernel.org](https://kernel.org). This kernel has been specially tuned for WSL 2, optimizing for size and performance to provide an amazing Linux experience on Windows. The kernel will be serviced by Windows updates, which means you will get the latest security fixes and kernel improvements without needing to manage it yourself. 58 | 59 | 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. 60 | 61 | Learn more in the [Release Notes for Windows Subsystem for Linux kernel](./kernel-release-notes.md). 62 | 63 | ### Increased file IO performance 64 | 65 | File intensive operations like `git clone`, `npm install`, `apt update`, `apt upgrade`, and more are all noticeably faster with WSL 2. 66 | 67 | The actual speed increase will depend on which app you're running and how it is interacting with the file system. Initial versions of WSL 2 run up to 20x faster compared to WSL 1 when unpacking a zipped tarball, and around 2-5x faster when using `git clone`, `npm install` and `cmake` on various projects. 68 | 69 | ### Full system call compatibility 70 | 71 | Linux binaries use system calls to perform functions such as accessing files, requesting memory, creating processes, and more. Whereas WSL 1 used a translation layer that was built by the WSL team, WSL 2 includes its own Linux kernel with full system call compatibility. Benefits include: 72 | 73 | - A whole new set of apps that you can run inside of WSL, such as **[Docker](tutorials/wsl-containers.md)** and more. 74 | 75 | - Any updates to the Linux kernel are immediately ready for use (you don't have to wait for the WSL team to implement updates and add the changes). 76 | 77 | ## Exceptions for using WSL 1 rather than WSL 2 78 | 79 | We recommend that you use WSL 2 as it offers faster performance and 100% system call compatibility. However, there are a few specific scenarios where you might prefer using WSL 1. Consider using WSL 1 if: 80 | 81 | - Your project files must be stored in the Windows file system. WSL 1 offers faster access to files mounted from Windows. 82 | - If you will be using your WSL Linux distribution to access project files on the Windows file system, and these files cannot be stored on the Linux file system, you will achieve faster performance across the OS files systems by using WSL 1. 83 | - A project which requires cross-compilation using both Windows and Linux tools on the same files. 84 | - File performance across the Windows and Linux operating systems is faster in WSL 1 than WSL 2, so if you are using Windows applications to access Linux files, you will currently achieve faster performance with WSL 1. 85 | - Your project needs access to a serial port or USB device. *However,* USB device support is now available for WSL 2 via the `USBIPD-WIN` project. See [Connect USB devices](./connect-usb.md) for set up steps. 86 | - 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). 87 | - You have strict memory requirements 88 | - 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). 89 | - For those using VirtualBox, be sure to use the latest version of both VirtualBox and WSL 2. See the [related FAQ](./faq.yml#will-i-be-able-to-run-wsl-2-and-other-3rd-party-virtualization-tools-such-as-vmware--or-virtualbox-). 90 | - 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 its 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). 91 | 92 | > [!NOTE] 93 | > 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). 94 | 95 | ## WSL in the Microsoft Store 96 | 97 | WSL has lifted the update functionality out of the Windows OS image into a package that is available via the Microsoft Store. This means faster updates and servicing as soon as they're available, rather than needing to wait for an update of your Windows operating system. 98 | 99 | WSL was originally included in the Windows operating system as an optional component that need to be enabled in order to install a Linux distribution. WSL in the Store has the same user experience, and is the same product, but receives updates and servicing as a store package, rather than as an entire OS update. Beginning in Windows version 19044 or higher, running the `wsl.exe --install` command will install the WSL servicing update from the Microsoft Store. ([See the blog post announcing this update](https://devblogs.microsoft.com/commandline/the-windows-subsystem-for-linux-in-the-microsoft-store-is-now-generally-available-on-windows-10-and-11)). If you are already using WSL, you can update to ensure that you're receiving the latest WSL features and servicing from the store by running `wsl.exe --update`. 100 | 101 | > [!NOTE] 102 | > If the Microsoft Store is inaccessible within your organization, you can still utilize this WSL version by appending `--web-download` to the `--update` command, such as `wsl --update --web-download`. You need to manually update WSL every time a new release becomes available using this method. 103 | -------------------------------------------------------------------------------- /WSL/connect-usb.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Connect USB devices 3 | description: Learn how to connect a USB device to your WSL 2 Linux distribution using usbipd-win. 4 | ms.date: 04/16/2024 5 | ms.topic: article 6 | --- 7 | 8 | # Connect USB devices 9 | 10 | This guide will walk through the steps necessary to connect a USB device to a Linux distribution running on WSL 2 using the USB/IP open-source project, [usbipd-win](https://github.com/dorssel/usbipd-win). 11 | 12 | Setting up the USB/IP project on your Windows machine will enable common developer USB scenarios like flashing an Arduino or accessing a smartcard reader. 13 | 14 | ## Prerequisites 15 | 16 | - Running Windows 11 (Build 22000 or later). *(Windows 10 support is possible, see note below).* 17 | - A machine with an x64 processor is required. (x86 and Arm64 are currently not supported with usbipd-win). 18 | - WSL is [installed and set up with the latest version](./install.md). 19 | - Linux distribution installed and [set to WSL 2](./basic-commands.md#set-wsl-version-to-1-or-2). 20 | 21 | > [!NOTE] 22 | > To check your Windows version and build number, select **Windows logo key + R**, type **winver**, select **OK**. You can update to the latest Windows version by selecting **Start** > **Settings** > **Windows Update** > **[Check for updates](ms-settings:windowsupdate)**. 23 | > To check your Linux kernel version, open your Linux distribution and enter the command: `uname -a`. To manually update to the latest kernel, open PowerShell and enter the command: `wsl --update`. 24 | 25 | > [!IMPORTANT] 26 | > WSL now supports both Windows 10 and Windows 11 via the Microsoft Store, meaning that Windows 10 users now have access to the latest kernel versions without needing to compile from source. See [WSL in the Microsoft Store is now generally available on Windows 10 and 11](https://devblogs.microsoft.com/commandline/the-windows-subsystem-for-linux-in-the-microsoft-store-is-now-generally-available-on-windows-10-and-11/) for info on how to update to the Store-supported version of WSL. If you are unable to update to the Store-supported version of WSL and automatically receive kernel updates, see the [USBIPD-WIN project repo](https://github.com/dorssel/usbipd-win/wiki/WSL-support) for instructions on connecting USB devices to a Linux distribution running on WSL 2 by building your own USBIP enabled WSL 2 kernel. 27 | 28 | ## Install the USBIPD-WIN project 29 | 30 | Support for connecting USB devices is not natively available in WSL, so you will need to install the open-source usbipd-win project. 31 | 32 | **Kernel requirements** 33 | 34 | To use USBIPD with Windows Subsystem for Linux (WSL), you need to have a [Linux kernel version of 5.10.60.1 or higher](https://github.com/dorssel/usbipd-win/wiki/WSL-support/6befeedd4c8e2a49468e4b03532c9a20478f8677). If the installed kernel version is older than 5.10.60.1, then it can be updated by first shutting down any running instances of WSL with `wsl --shutdown`, then running the command: `wsl --update`. 35 | 36 | **Install USBIPD on WSL** 37 | 38 | 1. Go to the [latest release page for the usbipd-win project](https://github.com/dorssel/usbipd-win/releases). 39 | 2. Select the .msi file, which will download the installer. (You may get a warning asking you to confirm that you trust this download). 40 | 3. Run the downloaded usbipd-win_x.msi installer file. 41 | 42 | > [!NOTE] 43 | > Alternatively, you can also install the usbipd-win project using [Windows Package Manager](/windows/package-manager/winget/) (winget). If you have already installed winget, just use the command: `winget install --interactive --exact dorssel.usbipd-win` to install usbipd-win. If you leave out --interactive, winget may immediately restart your computer if that is required to install the drivers. 44 | 45 | This will install: 46 | 47 | - A service called `usbipd` (display name: USBIP Device Host). You can check the status of this service using the Services app from Windows. 48 | - A command line tool `usbipd`. The location of this tool will be added to the PATH environment variable. 49 | - A firewall rule called `usbipd` to allow all local subnets to connect to the service. You can modify this firewall rule to fine tune access control. 50 | 51 | ## Attach a USB device 52 | 53 | Before attaching your USB device, ensure that a WSL command line is open. This will keep the WSL 2 lightweight VM active. 54 | 55 | > [!NOTE] 56 | > This doc assumes that you have [`usbipd-win 4.0.0` or higher installed](https://github.com/dorssel/usbipd-win/releases/latest) 57 | 58 | 1. List all of the USB devices connected to Windows by opening PowerShell in *administrator* mode and entering the following command. Once the devices are listed, select and copy the bus ID of the device you’d like to attach to WSL. 59 | 60 | ```powershell 61 | usbipd list 62 | ``` 63 | 64 | 2. Before attaching the USB device, the command `usbipd bind` must be used to share the device, allowing it to be attached to WSL. This requires administrator privileges. Select the bus ID of the device you would like to use in WSL and run the following command. After running the command, verify that the device is shared using the command `usbipd list` again. 65 | 66 | ```powershell 67 | usbipd bind --busid 4-4 68 | ``` 69 | 70 | 3. To attach the USB device, run the following command. (You no longer need to use an elevated administrator prompt.) Ensure that a WSL command prompt is open in order to keep the WSL 2 lightweight VM active. Note that as long as the USB device is attached to WSL, it cannot be used by Windows. Once attached to WSL, the USB device can be used by any distribution running as WSL 2. Verify that the device is attached using `usbipd list`. From the WSL prompt, run `lsusb` to verify that the USB device is listed and can be interacted with using Linux tools. 71 | 72 | ```powershell 73 | usbipd attach --wsl --busid 74 | ``` 75 | 76 | 3. Open Ubuntu (or your preferred WSL command line) and list the attached USB devices using the command: 77 | 78 | ```bash 79 | lsusb 80 | ``` 81 | 82 | You should see the device you just attached and be able to interact with it using normal Linux tools. Depending on your application, you may need to configure udev rules to allow non-root users to access the device. 83 | 84 | 4. Once you are done using the device in WSL, you can either physically disconnect the USB device or run this command from PowerShell: 85 | 86 | ```powershell 87 | usbipd detach --busid 88 | ``` 89 | 90 | To learn more about how this works, see the [Windows Command Line Blog](https://devblogs.microsoft.com/commandline/connecting-usb-devices-to-wsl/#how-it-works) and the [usbipd-win repo on GitHub](https://devblogs.microsoft.com/commandline/connecting-usb-devices-to-wsl/#how-it-works). 91 | 92 | For a video demonstration, see [WSL 2: Connect USB devices (Tabs vs Spaces show)](https://www.youtube.com/watch?v=I2jOuLU4o8E). 93 | -------------------------------------------------------------------------------- /WSL/docfx.json: -------------------------------------------------------------------------------- 1 | { 2 | "build": { 3 | "content": [ 4 | { 5 | "files": [ 6 | "**/*.md", 7 | "**/**.yml" 8 | ], 9 | "exclude": [ 10 | "**/obj/**", 11 | "**/includes/**", 12 | "README.md", 13 | "LICENSE", 14 | "LICENSE-CODE", 15 | "ThirdPartyNotices" 16 | ] 17 | } 18 | ], 19 | "resource": [ 20 | { 21 | "files": [ 22 | "**/*.png", 23 | "**/*.gif", 24 | "**/*.jpg", 25 | "**/*.svg" 26 | ], 27 | "exclude": [ 28 | "**/obj/**", 29 | "**/includes/**" 30 | ] 31 | } 32 | ], 33 | "overwrite": [], 34 | "externalReference": [], 35 | "globalMetadata": { 36 | "breadcrumb_path": "/windows/wsl/breadcrumb/toc.json", 37 | "uhfHeaderId": "MSDocsHeader-Windows", 38 | "recommendations" : true, 39 | "feedback_product_url": "https://github.com/Microsoft/wsl/issues", 40 | "feedback_system": "OpenSource", 41 | "open_source_feedback_contributorGuideUrl": "https://learn.microsoft.com/contribute/content/how-to-write-quick-edits", 42 | "open_source_feedback_issueTitle": "", 43 | "open_source_feedback_issueLabels": "needs-triage", 44 | "open_source_feedback_issueUrl": "https://github.com/MicrosoftDocs/wsl/issues/new?template=doc-issue.yml", 45 | "open_source_feedback_productLogoLightUrl": "https://learn.microsoft.com/windows/wsl/media/wsl-icon.svg", 46 | "open_source_feedback_productLogoDarkUrl": "https://learn.microsoft.com/windows/wsl/media/wsl-icon.svg", 47 | "open_source_feedback_productName": "Windows Subsystem for Linux", 48 | "ms.service": "dev-environment", 49 | "ms.subservice": "windows-subsystem-for-linux", 50 | "author": "mattwojo", 51 | "ms.author": "mattwoj", 52 | "ms.reviewer": "crloewen", 53 | "searchScope": ["WSL"], 54 | "adobe-target": true, 55 | "contributors_to_exclude": [ 56 | "VSC-Service-Account" 57 | ] 58 | }, 59 | "contributors_to_exclude": [ 60 | "VSC-Service-Account" 61 | ], 62 | "fileMetadata": {}, 63 | "template": [], 64 | "dest": "wsl", 65 | "markdownEngineName": "markdig" 66 | } 67 | } 68 | -------------------------------------------------------------------------------- /WSL/enterprise.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Set up Windows Subsystem for Linux for your company 3 | description: Resources and instructions on how to best use the Windows Subsystem for Linux in an Enterprise environment. 4 | ms.date: 08/16/2024 5 | ms.topic: article 6 | --- 7 | 8 | # Enterprise environment: Set up Windows Subsystem for Linux for your company 9 | 10 | This guidance is intended for IT Administrators or Security Analysts responsible for setting up enterprise work environments with the goal of distributing software across multiple machines and maintaining a consistent level of security settings across those work machines. 11 | 12 | Many companies use [Microsoft Intune](/mem/intune/) and [Microsoft Defender](/microsoft-365/security/defender/) to manage these security settings. However, setting up WSL and accessing Linux distributions in this context requires some specific setup. This guidance provides what you need to know to enable the secure use of Linux with WSL in an enterprise environment. 13 | 14 | ## Recommended Enterprise set up with Microsoft Defender for Endpoint, Intune, and Advanced Networking Controls 15 | 16 | There are a variety of ways to set up a secure enterprise environment, but we recommend the following for setting up a secure environment that utilizes WSL. 17 | 18 | ### Pre-requisites 19 | 20 | To get started ensure that all enterprise devices have the following minimum versions installed: 21 | 22 | * Windows 10 22H2 or higher, or Windows 11 22H2 or higher 23 | * Advanced networking features are only available on Windows 11 22H2 or higher. 24 | * [WSL version 2.0.9](https://github.com/microsoft/WSL/releases) or higher 25 | - You can check the WSL version by running `wsl --version`. 26 | 27 | ### Enable Microsoft Defender for Endpoint (MDE) integration 28 | 29 | [Microsoft Defender for Endpoint](/microsoft-365/security/defender-endpoint/microsoft-defender-endpoint) is an enterprise endpoint security platform designed to help enterprise networks prevent, detect, investigate, and respond to advanced threats. MDE now integrates with WSL as a [WSL plugin](./wsl-plugins.md), which allows security teams to see and continuously monitor for security events in all running WSL distributions with Defender for Endpoint while minimally impacting performance on developer workloads. 30 | 31 | See [Microsoft Defender for Endpoint plug-in for WSL](/microsoft-365/security/defender-endpoint/mde-plugin-wsl) to learn more about how to get started. 32 | 33 | ### Configure recommended settings with Intune 34 | 35 | [Microsoft Intune](/mem/intune/fundamentals/what-is-intune) is a cloud-based endpoint management solution. It manages user access to organizational resources and simplifies app and device management across your many devices, including mobile devices, desktop computers, and virtual endpoints. You can use Microsoft Intune to manage devices inside of your organization, which now also includes managing access to WSL and its key security settings. 36 | 37 | See [Intune settings for WSL](./intune.md) for guidance on using InTune to manage WSL as a Windows component and the recommended settings. 38 | 39 | ### Use advanced networking features and controls 40 | 41 | Starting from Windows 11 22H2 and WSL 2.0.9 or later, Windows firewall rules will automatically apply to WSL. This ensures that the firewall rules set on the Windows host will automatically apply to all WSL distributions by default. For guidance on customizing the firewall settings for WSL, visit [Configure Hyper-V firewall](/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall). 42 | 43 | Additionally, we recommend configuring [settings under `[wsl2]` in the `.wslconfig` file](/windows/wsl/wsl-config#configuration-setting-for-wslconfig) to suit your specific Enterprise scenario. 44 | 45 | #### Mirrored mode networking 46 | 47 | `networkingMode=mirrored` enables mirrored mode networking. This new networking mode improves compatibility with complex networking environments, especially VPNs and more, as well as adding support for new networking features unavailable in the default NAT mode like IPv6. 48 | 49 | #### DNS Tunneling 50 | 51 | `dnsTunneling=true` changes how WSL obtains DNS information. This setting improves compatibility in different networking environments, and makes use of virtualization features to obtain DNS information rather than a networking packet. It's recommended to turn this on if experiencing any connectivity issues, and can be especially helpful when using VPNs, advanced firewall settings, and more. 52 | 53 | #### Auto proxy 54 | 55 | `autoProxy=true` enforces WSL to use Windows' HTTP proxy information. We recommend turning this setting on when using a proxy on Windows, as it will make that proxy automatically apply to your WSL distributions. 56 | 57 | ## Creating a custom WSL image 58 | 59 | What is commonly referred to as an "image", is simply a snapshot of your software and its components saved to a file. In the case of the Windows Subsystem for Linux, your image would consist of the subsystem, its distributions, and whatever software and packages are installed on the distribution. 60 | 61 | To begin creating your WSL image, first [install the Windows Subsystem for Linux](./install.md). 62 | 63 | Once installed, use the [Microsoft Store](https://apps.microsoft.com/search?query=wsl&hl) to download and install the Linux distribution that’s right for you. 64 | 65 | ### Exporting your WSL image 66 | 67 | Export your custom WSL image by running wsl --export ` `, which will wrap your image in a tar file and make it ready for distribution on to other machines. You can [create custom distributions including CentOS, RedHat and more using the custom distro guide](./use-custom-distro.md). 68 | 69 | ## Distributing your WSL image 70 | 71 | Distribute the WSL image from a share or storage device by running wsl --import ` `, which will import the specified tar file as a new distribution. 72 | 73 | ## Update and patch Linux distributions and packages 74 | 75 | Using Linux configuration manager tools is strongly recommended for monitoring and managing Linux user space. There are a host of Linux configuration managers to choose from. See this blog post on [Running Puppet quickly in WSL 2](http://www.craigloewen.com/blog/2019/12/04/running-puppet-quickly-in-wsl2/). 76 | 77 | ## Windows file system access 78 | 79 | When a Linux binary inside of WSL accesses a Windows file, it does so with the user permissions of the Windows user that ran `wsl.exe`. So even though a Linux user has root access inside of WSL, they cannot do Windows administrator level operations on Windows if the Windows user does not have those permission. With regards to Windows file and Windows executable access from WSL, running a shell like `bash` has the same security level permissions as running `powershell` from Windows as that user. 80 | 81 | ### Supported 82 | 83 | * Sharing an approved image internally using `wsl --import` and `wsl --export` 84 | * Creating your own WSL distro for your Enterprise using the [WSL Distro Launcher repo](https://github.com/microsoft/WSL-DistroLauncher) 85 | * Monitor security events inside of WSL distros using Microsoft Defender for Endpoint (MDE) 86 | * Use firewall settings to control networking in WSL (Includes syncing Windows firewall settings to WSL) 87 | * Control access to WSL and its key security settings with Intune or group policy 88 | 89 | Here's a list of features for which we don't yet have support for, but are investigating. 90 | 91 | ### Currently unsupported 92 | 93 | Below is a list of commonly asked features that are currently unsupported within WSL. These requests are on our backlog and we are investigating ways to add them. 94 | 95 | * Managing updates and patching of the Linux distributions and packages using Windows tools 96 | * Having Windows update also update WSL distro contents 97 | * Controlling which distributions users in your Enterprise can access 98 | * Controlling root access for users 99 | -------------------------------------------------------------------------------- /WSL/file-permissions.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: File Permissions for WSL 3 | description: Understanding how WSL determines file permissions in Windows 4 | keywords: File permissions, bash, wsl, wsl2, windows, windows subsystem for linux, windows subsystem, ubuntu, debian, suse, windows 10 5 | ms.date: 09/27/2021 6 | ms.topic: article 7 | --- 8 | 9 | # File Permissions for WSL 10 | 11 | This page details how Linux file permissions are interpreted across the Windows Subsystem for Linux, especially when accessing resources inside of Windows on the NT file system. This documentation assumes a basic understanding of the [Linux file system permissions structure](https://wiki.archlinux.org/title/File_permissions_and_attributes) and the [umask command](https://en.wikipedia.org/wiki/Umask). 12 | 13 | When accessing Windows files from WSL the file permissions are either calculated from Windows permissions, or are read from metadata that has been added to the file by WSL. This metadata is not enabled by default. 14 | 15 | ## WSL metadata on Windows files 16 | 17 | When metadata is enabled as a mount option in WSL, extended attributes on Windows NT files can be added and interpreted to supply Linux file system permissions. 18 | 19 | WSL can add four NTFS extended attributes: 20 | 21 | | Attribute Name | Description | 22 | | --- | --- | 23 | | $LXUID | User Owner ID | 24 | | $LXGID | Group Owner ID | 25 | | $LXMOD | File mode (File systems permission octals and type, e.g: 0777) | 26 | | $LXDEV | Device, if it is a device file | 27 | 28 | Additionally, any file that is not a regular file or directory (e.g: symlinks, FIFOs, block devices, unix sockets, and character devices) also have an NTFS [reparse point](/windows/win32/fileio/reparse-points). This makes it much faster to determine the kind of file in a given directory without having to query its extended attributes. 29 | 30 | ## File Access Scenarios 31 | 32 | Below is a description of how permissions are determined when accessing files in different ways using the Windows Subsystem for Linux. 33 | 34 | ### Accessing Files in the Windows drive file system (DrvFS) from Linux 35 | 36 | These scenarios occur when you are accessing your Windows files from WSL, most likely via `/mnt/c`. 37 | 38 | #### Reading file permissions from an existing Windows file 39 | 40 | The result depends on if the file already has existing metadata. 41 | 42 | ##### DrvFS file does not have metadata (default) 43 | 44 | If the file has no metadata associated with it then we translate the effective permissions of the Windows user to read/write/execute bits and set them to this as the same value for user, group, and other. For example, if your Windows user account has read and execute access but not write access to the file then this will be shown as `r-x` for user, group and other. If the file has the 'Read Only' attribute set in Windows then we do not grant write access in Linux. 45 | 46 | ##### The file has metadata 47 | 48 | If the file has metadata present, we simply use those metadata values instead of translating effective permissions of the Windows user. 49 | 50 | #### Changing file permissions on an existing Windows file using chmod 51 | 52 | The result depends on if the file already has existing metadata. 53 | 54 | ##### chmod file does not have metadata (default) 55 | 56 | Chmod will only have one effect, if you remove all the write attributes of a file then the 'read only' attribute on the Windows file will be set, since this is the same behavior as CIFS (Common Internet File System) which is the SMB (Server Message Block) client in Linux. 57 | 58 | ##### chmod file has metadata 59 | 60 | Chmod will change or add metadata depending on the file's already existing metadata. 61 | 62 | Please keep in mind that you cannot give yourself more access than what you have on Windows, even if the metadata says that is the case. For example, you could set the metadata to display that you have write permissions to a file using `chmod 777`, but if you tried to access that file you would still not be able to write to it. This is thanks to interoperability, as any read or write commands to Windows files are routed through your Windows user permissions. 63 | 64 | #### Creating a file in DriveFS 65 | 66 | The result depends on if metadata is enabled. 67 | 68 | ##### Metadata is not enabled (default) 69 | 70 | The Windows permissions of the newly created file will be the same as if you created the file in Windows without a specific security descriptor, it will inherit the parent's permissions. 71 | 72 | ##### Metadata is enabled 73 | 74 | The file's permission bits are set to follow the Linux umask, and the file will be saved with metadata. 75 | 76 | #### Which Linux user and Linux group owns the file? 77 | 78 | The result depends on if the file already has existing metadata. 79 | 80 | ##### User file does not have metadata (default) 81 | 82 | In the default scenario, when automounting Windows drives, we specify that the user ID (UID) for any file is set to the user ID of your WSL user and the group ID (GID) is set to the principal group ID of your WSL user. 83 | 84 | ##### User file has metadata 85 | 86 | The UID and GID specified in the metadata is applied as the user owner and group owner of the file. 87 | 88 | ### Accessing Linux files from Windows using `\\wsl$` 89 | 90 | Accessing Linux files via `\\wsl$` will use the default user of your WSL distribution. Therefore any Windows app accessing Linux files will have the same permissions as the default user. 91 | 92 | #### Creating a new file 93 | 94 | The default umask is applied when creating a new file inside of a WSL distribution from Windows. The default umask is `022`, or in other words it allows all permissions except write permissions to groups and others. 95 | 96 | ### Accessing files in the Linux root file system from Linux 97 | 98 | Any files created, modified, or accessed in the Linux root file system follow standard Linux conventions, such as applying the umask to a newly created file. 99 | 100 | ## Configuring file permissions 101 | 102 | You can configure your file permissions inside of your Windows drives using the mount options in wsl.conf. The mount options allow you to set `umask`, `dmask` and `fmask` permissions masks. The `umask` is applied to all files, the `dmask` is applied just to directories and the `fmask` is applied just to files. These permission masks are then put through a logical OR operation when being applied to files, e.g: If you have a `umask` value of `023` and an `fmask` value of `022` then the resulting permissions mask for files will be `023`. 103 | 104 | Learn more: [Per distribution configuration options with wsl.conf](/windows/wsl/wsl-config#per-distribution-configuration-options-with-wslconf). 105 | -------------------------------------------------------------------------------- /WSL/filesystems.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Working across file systems 3 | description: Learn about the considerations and interop commands available when working across Windows and Linux file systems with WSL. 4 | keywords: wsl, Linux, Windows, file systems, interop, across directories, mnt 5 | ms.date: 09/27/2021 6 | ms.topic: article 7 | --- 8 | 9 | # Working across Windows and Linux file systems 10 | 11 | There are a number of considerations to keep in mind when working between Windows and Linux file systems. We have outlined a few of them for you in this guide, including some examples of interoperability support for mixing Windows and Linux-based commands. 12 | 13 | ## File storage and performance across file systems 14 | 15 | We recommend against working across operating systems with your files, unless you have a specific reason for doing so. For the fastest performance speed, store your files in the WSL file system if you are working in a Linux command line (Ubuntu, OpenSUSE, etc). If you're working in a Windows command line (PowerShell, Command Prompt), store your files in the Windows file system. 16 | 17 | For example, when storing your WSL project files: 18 | 19 | - Use the Linux file system root directory: `/home//Project` 20 | - Not the Windows file system root directory: `/mnt/c/Users//Project$` or `C:\Users\\Project` 21 | 22 | When you see `/mnt/` in the file path of a WSL command line, it means that you are working from a mounted drive. So the Windows file system C:/ drive (`C:\Users\\Project`) will look like this when mounted in a WSL command line: `/mnt/c/Users//Project$`. It is possible to store your project files on a mounted drive, but your performance speed will improve if you store them directly on the `\\wsl$` drive. 23 | 24 | ## View your current directory in Windows File Explorer 25 | 26 | You can view the directory where your files are stored by opening the Windows File Explorer from the command line, using: 27 | 28 | ```bash 29 | explorer.exe . 30 | ``` 31 | 32 | Alternatively, you can also use the command: `powershell.exe /c start .` Be sure to add the period at the end of the command to open the current directory. 33 | 34 | To view all of your available Linux distributions and their root file systems in Windows File explorer, in the address bar enter: `\\wsl$` 35 | 36 | ![View project files in Windows File Explorer](media/windows-file-explorer.png) 37 | 38 | ## Filename and directory case sensitivity 39 | 40 | Case sensitivity determines whether uppercase (FOO.txt) and lowercase (foo.txt) letters are handled as distinct (case-sensitive) or equivalent (case-insensitive) in a file name or directory. Windows and Linux file systems handle case sensitivity in different ways - Windows is case-insensitive and Linux is case-sensitive. Learn more about how to adjust case sensitivity, particularly when mounting disks with WSL, in the [Adjust case sensitivity](./case-sensitivity.md) how-to article. 41 | 42 | ## Interoperability between Windows and Linux commands 43 | 44 | Windows and Linux tools and commands can be used interchangeably with WSL. 45 | 46 | - Run Windows tools (ie. notepad.exe) from a Linux command line (ie. Ubuntu). 47 | - Run Linux tools (ie. grep) from a Windows command line (ie. PowerShell). 48 | - Share environment variables between Linux and Windows. (Build 17063+) 49 | 50 | ## Run Linux tools from a Windows command line 51 | 52 | Run Linux binaries from the Windows Command Prompt (CMD) or PowerShell using `wsl ` (or `wsl.exe `). 53 | 54 | For example: 55 | 56 | ```powershell 57 | C:\temp> wsl ls -la 58 | <- contents of C:\temp -> 59 | ``` 60 | 61 | Binaries invoked in this way: 62 | 63 | - Use the same working directory as the current CMD or PowerShell prompt. 64 | - Run as the WSL default user. 65 | - Have the same Windows administrative rights as the calling process and terminal. 66 | 67 | The Linux command following `wsl` (or `wsl.exe`) is handled like any command run in WSL. Things such as sudo, piping, and file redirection work. 68 | 69 | Example using sudo to update your default Linux distribution: 70 | 71 | ```powershell 72 | C:\temp> wsl sudo apt-get update 73 | ``` 74 | 75 | Your default Linux distribution user name will be listed after running this command and you will be asked for your password. After entering your password correctly, your distribution will download updates. 76 | 77 | ## Mixing Linux and Windows commands 78 | 79 | Here are a few examples of mixing Linux and Windows commands using PowerShell. 80 | 81 | To use the Linux command `ls -la` to list files and the PowerShell command `findstr` to filter the results for words containing "git", combine the commands: 82 | 83 | ```powershell 84 | wsl ls -la | findstr "git" 85 | ``` 86 | 87 | To use the PowerShell command `dir` to list files and the Linux command `grep` to filter the results for words containing "git", combine the commands: 88 | 89 | ```powershell 90 | C:\temp> dir | wsl grep git 91 | ``` 92 | 93 | To use the Linux command `ls -la` to list files and the PowerShell command `> out.txt` to print that list to a text file named "out.txt", combine the commands: 94 | 95 | ```powershell 96 | C:\temp> wsl ls -la > out.txt 97 | ``` 98 | 99 | The commands passed into `wsl.exe` are forwarded to the WSL process without modification. File paths must be specified in the WSL format. 100 | 101 | To use the Linux command `ls -la` to list files in the `/proc/cpuinfo` Linux file system path, using PowerShell: 102 | 103 | ```powershell 104 | C:\temp> wsl ls -la /proc/cpuinfo 105 | ``` 106 | 107 | To use the Linux command `ls -la` to list files in the `C:\Program Files` Windows file system path, using PowerShell: 108 | 109 | ```powershell 110 | C:\temp> wsl ls -la "/mnt/c/Program Files" 111 | ``` 112 | 113 | ## Run Windows tools from Linux 114 | 115 | WSL can run Windows tools directly from the WSL command line using `[tool-name].exe`. For example, `notepad.exe`. 116 | 117 | Applications run this way have the following properties: 118 | 119 | - Retain the working directory as the WSL command prompt (for the most part -- exceptions are explained below). 120 | - Have the same permission rights as the WSL process. 121 | - Run as the active Windows user. 122 | - Appear in the Windows Task Manager as if directly executed from the CMD prompt. 123 | 124 | Windows executables run in WSL are handled similarly to native Linux executables -- piping, redirects, and even backgrounding work as expected. 125 | 126 | To run the Windows tool `ipconfig.exe`, use the Linux tool `grep` to filter the "IPv4" results, and use the Linux tool `cut` to remove the column fields, from a Linux distribution (for example, Ubuntu) enter: 127 | 128 | ```bash 129 | ipconfig.exe | grep IPv4 | cut -d: -f2 130 | ``` 131 | 132 | Let's try an example mixing Windows and Linux commands. Open your Linux distribution (ie. Ubuntu) and create a text file: `touch foo.txt`. Now use the Linux command `ls -la` to list the direct files and their creation details, plus the Windows PowerShell tool `findstr.exe` to filter the results so only your `foo.txt` file shows in the results: 133 | 134 | ```bash 135 | ls -la | findstr.exe foo.txt 136 | ``` 137 | 138 | Windows tools must include the file extension, match the file case, and be executable. Non-executables including batch scripts. CMD native commands like `dir` can be run with `cmd.exe /C` command. 139 | 140 | For example, list the contents of your Windows files system C:\ directory, by entering: 141 | 142 | ```bash 143 | cmd.exe /C dir 144 | ``` 145 | 146 | Or use the `ping` command to send an echo request to the microsoft.com website: 147 | 148 | ```bash 149 | ping.exe www.microsoft.com 150 | ``` 151 | 152 | Parameters are passed to the Windows binary unmodified. As an example, the following command will open `C:\temp\foo.txt` in `notepad.exe`: 153 | 154 | ```bash 155 | notepad.exe "C:\temp\foo.txt" 156 | ``` 157 | 158 | This will also work: 159 | 160 | ```bash 161 | notepad.exe C:\\temp\\foo.txt 162 | ``` 163 | 164 | ## Share environment variables between Windows and WSL with WSLENV 165 | 166 | WSL and Windows share a special environment variable, `WSLENV`, created to bridge Windows and Linux distributions running on WSL. 167 | 168 | Properties of `WSLENV` variable: 169 | 170 | - It is shared; it exists in both Windows and WSL environments. 171 | - It is a list of environment variables to share between Windows and WSL. 172 | - It can format environment variables to work well in Windows and WSL. 173 | - It can assist in the flow between WSL and Win32. 174 | 175 | > [!NOTE] 176 | > Prior to 17063, only Windows environment variable that WSL could access was `PATH` (so you could launch Win32 executables from under WSL). Starting in 17063, `WSLENV` begins being supported. 177 | > WSLENV is case sensitive. 178 | 179 | ## WSLENV flags 180 | 181 | There are four flags available in `WSLENV` to influence how the environment variable is translated. 182 | 183 | `WSLENV` flags: 184 | 185 | - `/p` - translates the path between WSL/Linux style paths and Win32 paths. 186 | - `/l` - indicates the environment variable is a list of paths. 187 | - `/u` - indicates that this environment variable should only be included when running WSL from Win32. 188 | - `/w` - indicates that this environment variable should only be included when running Win32 from WSL. 189 | 190 | Flags can be combined as needed. 191 | 192 | [Read more about WSLENV](https://devblogs.microsoft.com/commandline/share-environment-vars-between-wsl-and-windows/), including FAQs and examples of setting the value of WSLENV to a concatenation of other pre-defined environment vars, each suffixed with a slash followed by flags to specify how the value should be translated and passing variables with a script. This article also includes an example for setting up a dev environment with the [Go programming language](https://golang.org/), configured to share a GOPATH between WSL and Win32. 193 | 194 | ## Disable interoperability 195 | 196 | Users may disable the ability to run Windows tools for a single WSL session by running the following command as root: 197 | 198 | ```bash 199 | echo 0 > /proc/sys/fs/binfmt_misc/WSLInterop 200 | ``` 201 | 202 | To re-enable Windows binaries, exit all WSL sessions and re-run bash.exe or run the following command as root: 203 | 204 | ```bash 205 | echo 1 > /proc/sys/fs/binfmt_misc/WSLInterop 206 | ``` 207 | 208 | Disabling interop will not persist between WSL sessions -- interop will be enabled again when a new session is launched. 209 | -------------------------------------------------------------------------------- /WSL/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Windows Subsystem for Linux Documentation 3 | description: Overview of the Windows Subsystem for Linux documentation. 4 | ms.topic: overview 5 | ms.date: 05/19/2025 6 | --- 7 | 8 | # Windows Subsystem for Linux Documentation 9 | 10 | 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. 11 | 12 | > [!div class="nextstepaction"] 13 | > [Install WSL](install.md) 14 | 15 | ## Learn more 16 | 17 | * [What is the Windows Subsystem for Linux (WSL)?](about.md) 18 | * [Windows Subsystem for Linux is now open source](https://blogs.windows.com/windowsdeveloper/2025/05/19/the-windows-subsystem-for-linux-is-now-open-source/) 19 | * [What's new with WSL 2?](compare-versions.md#whats-new-in-wsl-2) 20 | * [Comparing WSL 1 and WSL 2](compare-versions.md) 21 | * [Frequently Asked Questions](faq.yml) 22 | 23 | :::image type="content" source="./media/wsl-opensource.png" alt-text="Screenshot of Satya introducing WSL going Open Source at the 2025 Build conference."::: 24 | 25 | ## Get started 26 | 27 | * [Install WSL](install.md) 28 | * [Install Linux on Windows Server](install-on-server.md) 29 | * [Manual install steps](install-manual.md) 30 | * [Best practices for setting up a WSL development environment](./setup/environment.md) 31 | 32 | ## Try WSL preview features by joining the Windows Insiders Program 33 | 34 | To try the most recent features or updates to WSL, join the [Windows Insiders Program](https://insider.windows.com/getting-started). Once you have joined Windows Insiders, you can choose the channel you would like to receive preview builds from inside the Windows settings menu. You can choose from: 35 | 36 | * Dev channel: Most recent updates, but low stability. 37 | * Beta channel: Ideal for early adopters, more reliable builds than the Dev channel. 38 | * Release Preview channel: Preview fixes and key features on the next version of Windows just before its available to the general public. 39 | 40 | ## Team blogs 41 | 42 | * [Overview post with a collection of videos and blogs](https://blogs.msdn.microsoft.com/commandline/learn-about-windows-console-and-windows-subsystem-for-linux-wsl/) 43 | * [Command-Line blog](https://blogs.msdn.microsoft.com/commandline/) (Active) 44 | * [Windows Subsystem for Linux Blog](/archive/blogs/wsl/) (Historical) 45 | 46 | ## Provide feedback 47 | 48 | * [GitHub issue tracker: WSL](https://github.com/microsoft/WSL/issues) 49 | * [GitHub issue tracker: WSL documentation](https://github.com/MicrosoftDocs/WSL/issues) 50 | 51 | ## Related videos 52 | 53 | **WSL BASICS** 54 | 55 | 1. [What is the Windows Subsystem for Linux (WSL)?](https://www.youtube.com/watch?v=NYGMY9c90Oo) | One Dev Question (0:40) 56 | 1. [I'm a Windows developer. Why should I use WSL? |](https://www.youtube.com/watch?v=sqdHy1rC2t4) One Dev Question (0:58) 57 | 1. [I'm a Linux developer. Why should I use WSL?](https://www.youtube.com/watch?v=75JBKfAqH3I) | One Dev Question (1:04) 58 | 1. [What is Linux?](https://www.youtube.com/watch?v=jx5I-8_arqM) | One Dev Question (1:31) 59 | 1. [What is a Linux distro?](https://www.youtube.com/watch?v=WnzKfwL3Iy0) | One Dev Question (1:04) 60 | 1. [How is WSL different than a virtual machine or dual booting?](https://www.youtube.com/watch?v=UMQ5GQix0rs) | One Dev Question 61 | 1. [Why was the Windows Subsystem for Linux created?](https://www.youtube.com/watch?v=b9I7NZHni5c) | One Dev Question (1:14) 62 | 1. [How do I access files on my computer in WSL?](https://www.youtube.com/watch?v=uUaFNRRS9yo&t=2s) | One Dev Question (1:41) 63 | 1. [How is WSL integrated with Windows?](https://www.youtube.com/watch?v=JuJ_Nx_bFEM) | One Dev Question (1:34) 64 | 1. [How do I configure a WSL distro to launch in the home directory in Terminal?](https://www.youtube.com/watch?v=n1YSFT5VK-Y) | One Dev Question (0:47) 65 | 1. [Can I use WSL for scripting?](https://www.youtube.com/watch?v=teI6WA48_Rg) | One Dev Question (1:04) 66 | 1. [Why would I want to use Linux tools on Windows?](https://www.youtube.com/watch?v=OeomwrHLAR4) | One Dev Question (1:20) 67 | 1. [In WSL, can I use distros other than the ones in the Microsoft Store?](https://www.youtube.com/watch?v=AfhDwVASD2c) | One Dev Question (1:03) 68 | 69 | **WSL DEMOS** 70 | 71 | 1. [WSL2: Code faster on the Windows Subsystem for Linux!](https://www.youtube.com/watch?v=MrZolfGm8Zk&t=3s) | Tabs vs Spaces (13:42) 72 | 1. [WSL: Run Linux GUI Apps](https://www.youtube.com/watch?v=kC3eWRPzeWw) | Tabs vs Spaces (17:16) 73 | 1. [WSL 2: Connect USB devices](https://www.youtube.com/watch?v=I2jOuLU4o8E) | Tabs vs Spaces (10:08) 74 | 1. [GPU Accelerated Machine Learning with WSL 2](https://www.youtube.com/watch?v=PdxXlZJiuxA) | Tabs vs Spaces (16:28) 75 | 1. [Visual Studio Code: Remote Dev with SSH, VMs, and WSL](https://www.youtube.com/watch?v=XkLjxr9iQ-8&t=1s) | Tabs vs Spaces (29:33) 76 | 1. [Windows Dev Tool Updates: WSL, Terminal, Package Manager, and more](https://www.youtube.com/watch?v=m5tt9mDRPSw) | Tabs vs Spaces (20:46) 77 | 1. [Build Node.JS apps with WSL](https://www.youtube.com/watch?v=lOXatmtBb88) | Highlight (3:15) 78 | 1. [New memory reclaim feature in WSL 2](https://www.youtube.com/watch?v=K9GPOHrZgr4) | Demo (6:01) 79 | 1. [Web development on Windows (in 2019)](https://www.youtube.com/watch?v=UxWN1BBr1bM) | Demo (10:39) 80 | 81 | **WSL DEEP DIVES** 82 | 83 | 1. [WSL on Windows 11 - Demos with Craig Loewen and Scott Hanselman](https://www.youtube.com/watch?v=pNwatyeXplY)| Windows Wednesday (35:48) 84 | 1. [WSL and Linux Distributions – Hayden Barnes and Kayla Cinnamon](https://www.youtube.com/watch?v=kCB3gO32SPs) | Windows Wednesday (37:00) 85 | 1. [Customize your terminal with Oh My Posh and WSL Linux distros](https://www.youtube.com/watch?v=uO_F5W2LbSk) | Windows Wednesday (33:14) 86 | 1. [Web dev Sarah Tamsin and Craig Loewen chat about web development, content creation, and WSL](https://www.youtube.com/watch?v=ySS8Re6LDTQ) | Dev Perspectives (12:22) 87 | 1. [How WSL accesses Linux files from Windows](https://www.youtube.com/watch?v=63wVlI9B3Ac&t=45s) | Deep dive (24:59) 88 | 1. [Windows subsystem for Linux architecture: a deep dive](https://www.youtube.com/watch?v=lwhMThePdIo) | Build 2019 (58:10) 89 | -------------------------------------------------------------------------------- /WSL/install-on-server.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Install Linux Subsystem on Windows Server 3 | description: Learn how to install the Linux Subsystem on Windows Server. WSL is available for installation on Windows Server 2019 (version 1709) and later. 4 | ms.date: 06/14/2022 5 | ms.topic: article 6 | --- 7 | 8 | # Windows Server Installation Guide 9 | 10 | The Windows Subsystem for Linux (WSL) is available for installation on Windows Server 2019 (version 1709) and later. This guide will walk through the steps of enabling WSL on your machine. 11 | 12 | ## Install WSL on Windows Server 2022 and 2025 Desktop Experience 13 | 14 | [Windows Server 2022](/windows-server/get-started/whats-new-in-windows-server-2022) now supports a simple WSL installation using the command: 15 | 16 | ```cmd 17 | wsl --install 18 | ``` 19 | 20 | You can now install everything you need to run WSL on Windows Server 2022 by entering this command in an **administrator** PowerShell or Windows Command Prompt and then restarting your machine. 21 | 22 | This command will enable the required optional components, download the latest Linux kernel, set WSL 2 as your default, and install a Linux distribution for you *(Ubuntu by default)*. 23 | 24 | See the standard WSL docs for more information on how to: 25 | 26 | - [Change the default Linux distribution installed](install.md#change-the-default-linux-distribution-installed). 27 | - [Set up your Linux username and password](./setup/environment.md#set-up-your-linux-username-and-password). 28 | - [Check which version of WSL you are running](./install.md#check-which-version-of-wsl-you-are-running) 29 | - [Update and upgrade packages](./setup/environment.md#update-and-upgrade-packages). 30 | - [Add additional distributions](./setup/environment.md#add-additional-distributions). 31 | - [Use Git with WSL](./tutorials/wsl-git.md). 32 | 33 | ## Install WSL on previous versions of Windows Server and Server Core 34 | 35 | To install WSL on Windows Server 2019 (version 1709+), as well as Server Core for 2019 and later you can follow the manual install steps below. 36 | 37 | ### Enable the Windows Subsystem for Linux 38 | 39 | Before you can run Linux distributions on Windows, you must enable the "Windows Subsystem for Linux" optional feature and reboot. 40 | 41 | Open PowerShell **as Administrator** and run: 42 | 43 | ```powershell 44 | Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux, VirtualMachinePlatform 45 | ``` 46 | 47 | ### Install the WSL Kernel update for WSL 2 48 | 49 | This is not necessary for server core 2025. 50 | 51 | ```powershell 52 | Invoke-WebRequest -Uri "https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi" -OutFile ".\wsl_update_x64.msi" 53 | Start-Process "msiexec.exe" -ArgumentList "/i .\wsl_update_x64.msi /quiet" -NoNewWindow -Wait 54 | ``` 55 | 56 | ### Download a Linux distribution 57 | 58 | See the [Downloading distributions](install-manual.md#downloading-distributions) section of the manual installation page for instructions and links to download your preferred Linux distribution. 59 | 60 | ### Extract and install a Linux distribution 61 | 62 | Now that you've downloaded a Linux distribution, in order to extract its contents and manually install, follow these steps. Not that you will be downloading an appx file that contains several appx files. In this example we will use debian. 63 | 64 | 1. List the contents of the appx using tar.exe: 65 | 66 | ```cmd 67 | > tar -tf .\debian.appx 68 | DistroLauncher-Appx_1.12.2.0_ARM64.appx 69 | DistroLauncher-Appx_1.12.2.0_scale-100.appx 70 | DistroLauncher-Appx_1.12.2.0_scale-125.appx 71 | DistroLauncher-Appx_1.12.2.0_scale-150.appx 72 | DistroLauncher-Appx_1.12.2.0_scale-400.appx 73 | DistroLauncher-Appx_1.12.2.0_x64.appx 74 | ``` 75 | In our example we have a x64 bit server so we want to install `DistroLauncher-Appx_1.12.2.0_x64.appx`. 76 | 77 | 2. Unzip the contents to a new folder called `\%USERPROFILE%\AppData\Local\DebianWSL\`. 78 | 79 | ```powershell 80 | mkdir "$env:USERPROFILE\AppData\Local\DebianWSL" | Out-Null 81 | tar -xf .\DistroLauncher-Appx_1.12.2.0_x64.appx -C $"env:USERPROFILE\AppData\Local\DebianWSL" 82 | ``` 83 | 84 | 4. Add your Linux distribution path to the Windows environment PATH (`C:\Users\Administrator\Ubuntu` in this example), using PowerShell: 85 | 86 | ```powershell 87 | $userenv = [System.Environment]::GetEnvironmentVariable("Path", "User") 88 | [System.Environment]::SetEnvironmentVariable("PATH", $userenv + ";$env:USERPROFILE\AppData\Local\DebianWSL", "User") 89 | ``` 90 | 91 | You can now launch your distribution from any path by typing `.exe`. For example: `ubuntu.exe`. Note that you will need to launch a new powershell instance from the start menu or log off and log on again in the case of Server core to refresh your path 92 | 93 | 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). 94 | -------------------------------------------------------------------------------- /WSL/install.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Install WSL 3 | 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. 4 | ms.date: 08/28/2023 5 | ms.topic: article 6 | adobe-target: true 7 | ms.custom: seo-windows-dev 8 | --- 9 | 10 | # How to install Linux on Windows with WSL 11 | 12 | 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. 13 | 14 | ## Prerequisites 15 | 16 | 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-manual.md). 17 | 18 | ## Install WSL command 19 | 20 | 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. 21 | 22 | ```powershell 23 | wsl --install 24 | ``` 25 | 26 | This command will enable the features necessary to run WSL and install the Ubuntu distribution of Linux. ([This default distribution can be changed](./basic-commands.md#install)). 27 | 28 | 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](./install-manual.md)**. 29 | 30 | 31 | 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. 32 | 33 | > [!NOTE] 34 | > 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. 35 | > To uninstall WSL, see [Uninstall legacy version of WSL](/windows/wsl/troubleshooting#uninstall-legacy-version-of-wsl) or [unregister or uninstall a Linux distribution](/windows/wsl/basic-commands#unregister-or-uninstall-a-linux-distribution). 36 | 37 | ## Change the default Linux distribution installed 38 | 39 | By default, the installed Linux distribution will be Ubuntu. This can be changed using the `-d` flag. 40 | 41 | - To change the distribution installed, enter: `wsl --install -d `. Replace `` with the name of the distribution you would like to install. 42 | - To see a list of available Linux distributions available for download through the online store, enter: `wsl --list --online` or `wsl -l -o`. 43 | - To install additional Linux distributions after the initial install, you may also use the command: `wsl --install -d `. 44 | 45 | > [!TIP] 46 | > 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`. 47 | 48 | If you run into an issue during the install process, check the [installation section of the troubleshooting guide](./troubleshooting.md#installation-issues). 49 | 50 | To install a Linux distribution that is not listed as available, you can [import any Linux distribution](/windows/wsl/use-custom-distro) using a TAR file. Or in some cases, [as with Arch Linux](https://wsldl-pg.github.io/ArchW-docs/How-to-Setup/), you can install using an `.appx` file. You can also create your own [custom Linux distribution](/windows/wsl/build-custom-distro) to use with WSL. 51 | 52 | ## Set up your Linux user info 53 | 54 | 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. 55 | 56 | ## Set up and best practices 57 | 58 | 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. 59 | 60 | ## Check which version of WSL you are running 61 | 62 | 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. 63 | 64 | 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. 65 | 66 | To set the default Linux distribution used with the `wsl` command, enter: `wsl -s ` or `wsl --set-default `, 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. 67 | 68 | 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. 69 | 70 | Learn more in the guide to [Basic commands for WSL](./basic-commands.md). 71 | 72 | ## Upgrade version from WSL 1 to WSL 2 73 | 74 | New Linux installations, installed using the `wsl --install` command, will be set to WSL 2 by default. 75 | 76 | 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. 77 | 78 | To see whether your Linux distribution is set to WSL 1 or WSL 2, use the command: `wsl -l -v`. 79 | 80 | 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. 81 | 82 | If you manually installed WSL prior to the `wsl --install` command being available, 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. 83 | 84 | 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. 85 | 86 | ## Ways to run multiple Linux distributions with WSL 87 | 88 | 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). 89 | 90 | There are several ways to run your Linux distributions once installed: 91 | 92 | - [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, 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) 93 | - 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 its own console window. 94 | - From Windows Command Prompt or PowerShell, you can enter the name of your installed distribution. For example: `ubuntu` 95 | - From Windows Command Prompt or PowerShell, you can open your default Linux distribution inside your current command line, by entering: `wsl.exe`. 96 | - 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. 97 | 98 | 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`. 99 | 100 | ## Want to try the latest WSL preview features? 101 | 102 | Try the most recent features or updates to WSL by joining the [Windows Insiders Program](https://insider.windows.com/getting-started). 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: 103 | 104 | - Dev channel: Most recent updates, but low stability. 105 | - Beta channel: Ideal for early adopters, more reliable builds than the Dev channel. 106 | - Release Preview channel: Preview fixes and key features on the next version of Windows just before its available to the general public. 107 | 108 | If you prefer not switching your Windows installation to a preview channel, you can still test the latest preview of WSL by issuing the command: `wsl --update --pre-release`. For more information check the [WSL Releases page on GitHub](https://github.com/Microsoft/WSL/releases). 109 | 110 | ## Additional resources 111 | 112 | - [Windows Command Line Blog: Install WSL with a single command now available in Windows 10 version 2004 and higher](https://devblogs.microsoft.com/commandline/install-wsl-with-a-single-command-now-available-in-windows-10-version-2004-and-higher/) 113 | -------------------------------------------------------------------------------- /WSL/intune.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Intune settings 3 | description: Available settings in Intune for the Windows Subsystem for Linux (WSL) 4 | ms.date: 01/10/2024 5 | ms.topic: article 6 | --- 7 | 8 | # Intune settings for WSL 9 | 10 | You can now use management tools like Intune to manage WSL as a Windows component. 11 | 12 | To access these settings please navigate to your Microsoft Intune admin center portal, and then select: `Devices -> Configuration Profiles -> Create -> New Policy -> Windows 10 and later -> Settings catalog`, create a name for the new profile and search for "Windows Subsystem for Linux" to see and add the full list of available settings. 13 | 14 | ## Recommended settings 15 | 16 | To maximize security in an enterprise environment, we recommend that you specify these settings: 17 | 18 | | Setting Name | Value | Description | 19 | | --- | --- | --- | 20 | | Allow the Inbox version of the Windows Subsystem for Linux | Disabled | When set to disabled, this policy disables the inbox version (optional component) of the Windows Subsystem For Linux. If this policy is disabled, only the store version of WSL can be used. [Learn more about the difference between Store WSL and Inbox WSL here](https://aka.ms/wslstoreinfo) | 21 | | Allow WSL1 | Disabled | When set to disabled, this policy disables WSL1. When disabled, only WSL2 distributions can be used. | 22 | | Allow the debug shell | Disabled | When set to disabled, this policy disables the debug shell (wsl.exe --debug-shell). This policy only applies to Store WSL. | 23 | | Allow custom kernel configuration | Disabled | When set to disabled, this policy disables custom kernel configuration via .wslconfig (wsl2.kernel). This policy only applies to Store WSL. | 24 | | Allow kernel command line configuration | Disabled | When set to disabled, this policy disables kernel command line configuration via .wslconfig (wsl2.kernelCommandLine). This policy only applies to Store WSL. | 25 | | Allow custom system distribution configuration | Disabled | When set to disabled, this policy disables custom system distribution configuration via .wslconfig (wsl2.systemDistro). This policy only applies to Store WSL. | 26 | | Allow custom networking configuration | Disabled | When set to disabled, this policy disables custom networking configuration via .wslconfig (wsl2.networkingmode). This policy only applies to Store WSL. | 27 | | Allow user setting firewall configuration | Disabled | When set to disabled, this policy disables firewall configuration via .wslconfig (wsl2.firewall). This policy only applies to Store WSL. | 28 | | Allow nested virtualization | Disabled | When set to disabled, this policy disables nested virtualization configuration via .wslconfig (wsl2.nestedVirtualization). This policy only applies to Store WSL. | 29 | | Allow kernel debugging | Disabled | When set to disabled, this policy disables kernel debugging configuration via .wslconfig (wsl2.kernelDebugPort). This policy only applies to Store WSL. | 30 | 31 | ## Control access to WSL 32 | 33 | The `AllowWSL`, `AllowInboxWSL`, and `AllowWSL1` settings control user access to WSL. You can configure these settings to enable or disable access to the in-Windows version of WSL, WSL 1 distros, or WSL itself. 34 | 35 | This will allow you to configure WSL to ensure that users are only using the latest version of WSL with Enterprise feature support. 36 | 37 | ## Control WSL commands 38 | 39 | `AllowDebugShell` and `AllowDiskMount` control whether users can run the `wsl --debug-shell` and `wsl --mount` commands. Learn more about how to [Mount a disk in WSL 2](./wsl2-mount-disk.md) using the `wsl --mount` command. 40 | 41 | ## Control access to WSL settings in `.wslconfig` 42 | 43 | The last group of settings that end with `*UserSettingConfigurable` control access to WSL advanced settings in `.wslconfig`. When these are set to disabled then users will only be able to use the default value for that setting, and not able to configure it to custom values. Learn more about [Configuration setting for .wslconfig](./wsl-config.md#configuration-settings-for-wslconfig), including a list of settings that can be configured globally for all Linux distributions running with WSL 2. 44 | 45 | ## Full list of available settings 46 | 47 | | Setting Name | Description | 48 | | --- | --- | 49 | | Allow the Windows Subsystem For Linux | When set to disabled, this policy disables access to the Windows Subsystem For Linux for all users on the machine. | 50 | | Allow the Inbox version of the Windows Subsystem For Linux | When set to disabled, this policy disables the inbox version (optional component) of the Windows Subsystem For Linux. If this policy is disabled, only the store version of WSL can be used. | 51 | | Allow WSL1 | When set to disabled, this policy disables WSL1. When disabled, only WSL2 distributions can be used. | 52 | | Allow the debug shell | When set to disabled, this policy disables the debug shell (wsl.exe --debug-shell). This policy only applies to Store WSL. | 53 | | Allow passthrough disk mount | When set to disabled, this policy disables passthrough disk mounting in WSL2 (wsl.exe --mount). This policy only applies to Store WSL. | 54 | | Allow custom kernel configuration | When set to disabled, this policy disables custom kernel configuration via .wslconfig (wsl2.kernel). This policy only applies to Store WSL. | 55 | | Allow kernel command line configuration | When set to disabled, this policy disables kernel command line configuration via .wslconfig (wsl2.kernelCommandLine). This policy only applies to Store WSL. | 56 | | Allow custom system distribution configuration | When set to disabled, this policy disables custom system distribution configuration via .wslconfig (wsl2.systemDistro). This policy only applies to Store WSL. | 57 | | Allow custom networking configuration | When set to disabled, this policy disables custom networking configuration via .wslconfig (wsl2.networkingmode). This policy only applies to Store WSL. | 58 | | Allow user setting firewall configuration | When set to disabled, this policy disables firewall configuration via .wslconfig (wsl2.firewall). This policy only applies to Store WSL. | 59 | | Allow nested virtualization | When set to disabled, this policy disables nested virtualization configuration via .wslconfig (wsl2.nestedVirtualization). This policy only applies to Store WSL. | 60 | | Allow kernel debugging | When set to disabled, this policy disables kernel debugging configuration via .wslconfig (wsl2.kernelDebugPort). This policy only applies to Store WSL. | 61 | -------------------------------------------------------------------------------- /WSL/kernel-release-notes.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Release Notes for WSL kernel 3 | description: Release notes for the Windows Subsystem for Linux. Updated monthly. 4 | keywords: release notes, wsl, windows, windows subsystem for linux, windowssubsystem, ubuntu, kernel 5 | ms.date: 09/27/2021 6 | ms.topic: article 7 | --- 8 | 9 | # Release Notes for Windows Subsystem for Linux kernel 10 | 11 | We've added support for WSL 2 distributions, [which use a full Linux kernel](https://devblogs.microsoft.com/commandline/shipping-a-linux-kernel-with-windows/). This Linux kernel is open source, with its source code available at the [WSL2-Linux-Kernel](https://github.com/microsoft/WSL2-Linux-Kernel) repository. This Linux kernel is delivered to your machine via Microsoft Update, and follows a separate release schedule to the Windows Subsystem for Linux which is delivered as part of the Windows image. 12 | 13 | ## 5.15.57.1 14 | 15 | *Release Date*: Prerelease 2022/08/02 16 | 17 | [Official GitHub release link](https://github.com/microsoft/WSL2-Linux-Kernel/releases/tag/linux-msft-wsl-5.15.57.1) 18 | 19 | - Initial release of the WSL2 kernel based on the v5.15 kernel series 20 | - Release rolling-lts/wsl/5.15.57.1 21 | - Update to stable kernel version v5.15.57 22 | - Enable Retbleed mitigations in x86_64 builds 23 | - Enable nftables and traffic control 24 | - Enable VGEM driver 25 | - Fix 9p filesystem regressions since the last v5.10 WSL2 kernel 26 | - Enable support for the Precision Time Protocol (PTP) clock device 27 | - Enable the Landlock Linux Security Module (LSM) 28 | - https://landlock.io/ 29 | - Enable the Miscellaneous Control Group (CGroup) 30 | - https://www.kernel.org/doc/html/v5.15/admin-guide/cgroup-v2.html#misc 31 | - Disable support for the Ceph Distributed File System 32 | 33 | ## 5.10.102.1 34 | 35 | *Release Date*: Prerelease 2022/05/09 36 | 37 | [Official Github release link](https://github.com/microsoft/WSL2-Linux-Kernel/releases/tag/linux-msft-wsl-5.10.102.1) 38 | 39 | - Release rolling-lts/wsl/5.10.102.1 40 | - Update to upstream stable kernel release 5.10.102 41 | - Disable unprivileged BPF by default 42 | - It can be re-enabled by setting the kernel.unprivileged_bpf_disabled sysctl to 0 43 | - Update Dxgkrnl Version to 2216 44 | - Fix out of bounds array access for ioctls[] 45 | - Implement wait for sync VM bus messages as “killable” to allow killing a process waiting for a synchronous call to the host 46 | - Flush device for termination when process is destroyed to avoid a deadlock when the guest process is killed 47 | 48 | ## 5.10.93.2 49 | 50 | *Release Date*: Prerelease 2022/02/08 51 | 52 | [Official Github release link](https://github.com/microsoft/WSL2-Linux-Kernel/releases/tag/linux-msft-wsl-5.10.93.2) 53 | 54 | - Release rolling-lts/wsl/5.10.93.2 55 | - Update to upstream stable kernel release 5.10.93 56 | - Enable CH341 and CP210X USB Serial drivers 57 | - Fix README.md build instructions to include dwarves dependency for pahole 58 | - Switched Dxgkrnl Version to 2111 59 | - Removed the limit of existing and total sysmem allocations 60 | - Properly flush the device for termination during process cleanup 61 | - Fixed SPDX-License-Identifier for d3dkmthk.h 62 | 63 | ## 5.10.81.1 64 | 65 | *Release Date*: Prerelease 2022/02/01 66 | 67 | [Official Github release link](https://github.com/microsoft/WSL2-Linux-Kernel/releases/tag/linux-msft-wsl-5.10.81.1) 68 | 69 | - Release rolling-lts/wsl/5.10.81.1 70 | - Update to upstream stable kernel release 5.10.81 71 | - Unify the kernel configurations by enabling missing options on arm64 72 | - Enable non-arch specific ACPI options 73 | - Enable options related to device-mapper RAID 74 | - Enable Btrfs 75 | - Enable LZO and ZSTD compression 76 | 77 | ## 5.10.74.3 78 | 79 | *Release Date*: Prerelease 2021/11/10 80 | 81 | [Official Github release link](https://github.com/microsoft/WSL2-Linux-Kernel/releases/tag/linux-msft-wsl-5.10.74.3) 82 | 83 | - Release rolling-lts/wsl/5.10.74.3 84 | - Update to upstream stable kernel release 5.10.74 85 | - Enable BPF Type Format (CONFIG_DEBUG_INFO_BTF) for use by eBPF tools (microsoft/WSL#7437) 86 | - Updated Dxgkrnl version to 2110 87 | - Enable the Buffer Sharing and Sync File Frameworks (CONFIG_DMA_SHARED_BUFFER, CONFIG_SYNC_FILE) for Dxgkrnl usage 88 | - Fix Dxgkrnl build failure with GCC versions older than 8.1 (microsoft/WSL#7558) 89 | 90 | ## 5.10.60.1 91 | 92 | *Release Date*: 2021/11/02 ( Prerelease 2021/10/05 ) 93 | 94 | [Official Github release link](https://github.com/microsoft/WSL2-Linux-Kernel/releases/tag/linux-msft-wsl-5.10.60.1) 95 | 96 | - Release rolling-lts/wsl/5.10.60.1 97 | - Update to upstream stable kernel release 5.10.60 98 | - Enable virtio-pmem with support for PCI BAR-relative addresses 99 | - Enable vPCI support under Hyper-V for arm64 100 | - Enable io_uring support 101 | - Enable USB over IP support 102 | - Enable paravirtualized spinlock support for x86_64 103 | - Refresh dxgkrnl driver to pick up bug fixes and code cleanups 104 | - Enable NFS client support for NFSv4.1 105 | - Enable USB kernel configuration options for interacting with an Arduino over USB 106 | - Provide a WSL2-specific README.md 107 | 108 | ## 5.10.43.3 109 | 110 | *Release Date*: Prerelease 2021/07/12 111 | 112 | [Official Github release link](https://github.com/microsoft/WSL2-Linux-Kernel/releases/tag/linux-msft-wsl-5.10.43.3) 113 | 114 | - Version rolling-lts/wsl/5.10.43.3 115 | - Update to upstream stable kernel release 5.10.43 116 | - Improved dxgkrnl driver 117 | - New revision of arm64 Linux on Hyper-V series (v9) 118 | - Always use the Hyper-V hypercall interface on arm64 guests to support running on all versions of Windows 119 | 120 | ## 5.10.16.3 121 | 122 | *Release Date*: 2021/07/20 ( Prerelease 2021/04/16 ) 123 | 124 | [Official Github release link](https://github.com/microsoft/WSL2-Linux-Kernel/releases/tag/linux-msft-wsl-5.10.16.3) 125 | 126 | - Fixes [GH 5324](https://github.com/microsoft/WSL/issues/5324) 127 | - Adds support for LUKS encrypted disks using wsl --mount 128 | 129 | ## 5.4.91 130 | 131 | *Release Date*: Prerelease 2021/02/22 132 | 133 | [Official Github release link](https://github.com/microsoft/WSL2-Linux-Kernel/releases/tag/linux-msft-5.4.91) 134 | 135 | ## 5.4.72 136 | *Release Date*: 2021/01/21 137 | 138 | [Official Github release link](https://github.com/microsoft/WSL2-Linux-Kernel/releases/tag/linux-msft-5.4.72) 139 | 140 | - Fix config for 5.4.72 141 | 142 | ## 5.4.51-microsoft-standard 143 | 144 | *Release Date*: Prerelease - 2020/10/22 145 | 146 | [Official Github release link](https://github.com/microsoft/WSL2-Linux-Kernel/releases/tag/linux-msft-5.4.51). 147 | 148 | - Stable release of 5.4.51 149 | 150 | ## 4.19.128-microsoft-standard 151 | 152 | *Release Date*: 2020/09/15 153 | 154 | [Official Github release link](https://github.com/microsoft/WSL2-Linux-Kernel/releases/tag/4.19.128-microsoft-standard). 155 | 156 | - This is a stable release of 4.19.128 157 | - Fix dxgkrnl driver IOCTL memory corruption 158 | 159 | ## 4.19.121-microsoft-standard 160 | 161 | *Release Date*: Prerelease 162 | 163 | [Official Github release link](https://github.com/microsoft/WSL2-Linux-Kernel/releases/tag/4.19.121-microsoft-standard). 164 | 165 | - Drivers: hv: vmbus: hook up dxgkrnl 166 | - Added support for GPU Compute 167 | 168 | ## 4.19.104-microsoft-standard 169 | 170 | *Release Date*: 2020/06/09 171 | 172 | [Official Github release link](https://github.com/microsoft/WSL2-Linux-Kernel/releases/tag/4.19.104-microsoft-standard). 173 | 174 | - Update WSL config for 4.19.104 175 | 176 | ## 4.19.84-microsoft-standard 177 | 178 | *Release Date*: 2019/12/11 179 | 180 | [Official Github release link](https://github.com/microsoft/WSL2-Linux-Kernel/releases/tag/4.19.84-microsoft-standard). 181 | 182 | - This is the 4.19.84 stable release 183 | -------------------------------------------------------------------------------- /WSL/media/UbuntuInstall.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/UbuntuInstall.png -------------------------------------------------------------------------------- /WSL/media/UbuntuStore.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/UbuntuStore.png -------------------------------------------------------------------------------- /WSL/media/WindowsServer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/WindowsServer.png -------------------------------------------------------------------------------- /WSL/media/appstorage-11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/appstorage-11.png -------------------------------------------------------------------------------- /WSL/media/appstorage.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/appstorage.png -------------------------------------------------------------------------------- /WSL/media/bash.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/bash.png -------------------------------------------------------------------------------- /WSL/media/distro.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/distro.png -------------------------------------------------------------------------------- /WSL/media/docker-dashboard.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/docker-dashboard.png -------------------------------------------------------------------------------- /WSL/media/docker-extension.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/docker-extension.png -------------------------------------------------------------------------------- /WSL/media/docker-extension2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/docker-extension2.png -------------------------------------------------------------------------------- /WSL/media/docker-extension3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/docker-extension3.png -------------------------------------------------------------------------------- /WSL/media/docker-extension4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/docker-extension4.png -------------------------------------------------------------------------------- /WSL/media/docker-running.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/docker-running.png -------------------------------------------------------------------------------- /WSL/media/docker-starting.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/docker-starting.png -------------------------------------------------------------------------------- /WSL/media/firewallrulemerging.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/firewallrulemerging.png -------------------------------------------------------------------------------- /WSL/media/ghost_adapter_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/ghost_adapter_1.png -------------------------------------------------------------------------------- /WSL/media/ghost_adapter_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/ghost_adapter_2.png -------------------------------------------------------------------------------- /WSL/media/ghost_adapter_3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/ghost_adapter_3.png -------------------------------------------------------------------------------- /WSL/media/git-versions.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/git-versions.gif -------------------------------------------------------------------------------- /WSL/media/gpu-acceleration.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/gpu-acceleration.gif -------------------------------------------------------------------------------- /WSL/media/localappdata.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/localappdata.png -------------------------------------------------------------------------------- /WSL/media/ls.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/ls.png -------------------------------------------------------------------------------- /WSL/media/mongodb.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/mongodb.png -------------------------------------------------------------------------------- /WSL/media/new-user.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/new-user.png -------------------------------------------------------------------------------- /WSL/media/ntfs-properties.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/ntfs-properties.png -------------------------------------------------------------------------------- /WSL/media/run-any-distro-customuser.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/run-any-distro-customuser.png -------------------------------------------------------------------------------- /WSL/media/run-any-distro-import.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/run-any-distro-import.png -------------------------------------------------------------------------------- /WSL/media/run-any-distro-tarfile.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/run-any-distro-tarfile.png -------------------------------------------------------------------------------- /WSL/media/server-appx-expand.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/server-appx-expand.png -------------------------------------------------------------------------------- /WSL/media/store.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/store.png -------------------------------------------------------------------------------- /WSL/media/system.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/system.png -------------------------------------------------------------------------------- /WSL/media/systemd-enable.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/systemd-enable.png -------------------------------------------------------------------------------- /WSL/media/terminal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/terminal.png -------------------------------------------------------------------------------- /WSL/media/troubleshoot-vitualdisk-compress.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/troubleshoot-vitualdisk-compress.png -------------------------------------------------------------------------------- /WSL/media/troubleshooting-virtualdisk-compress.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/troubleshooting-virtualdisk-compress.png -------------------------------------------------------------------------------- /WSL/media/ubuntu-logo112.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/ubuntu-logo112.png -------------------------------------------------------------------------------- /WSL/media/vs-target-system.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/vs-target-system.png -------------------------------------------------------------------------------- /WSL/media/vscode-remote-command-palette.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/vscode-remote-command-palette.png -------------------------------------------------------------------------------- /WSL/media/vscode-remote-indicator.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/vscode-remote-indicator.png -------------------------------------------------------------------------------- /WSL/media/vscode-remote-wsl-extensions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/vscode-remote-wsl-extensions.png -------------------------------------------------------------------------------- /WSL/media/vscode-run-config.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/vscode-run-config.png -------------------------------------------------------------------------------- /WSL/media/vscode-running-in-container.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/vscode-running-in-container.png -------------------------------------------------------------------------------- /WSL/media/windows-defender-firewall-settings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/windows-defender-firewall-settings.png -------------------------------------------------------------------------------- /WSL/media/windows-file-explorer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/windows-file-explorer.png -------------------------------------------------------------------------------- /WSL/media/windowsFeatures.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/windowsFeatures.png -------------------------------------------------------------------------------- /WSL/media/wsl-architecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/wsl-architecture.png -------------------------------------------------------------------------------- /WSL/media/wsl-gui-apps.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/wsl-gui-apps.png -------------------------------------------------------------------------------- /WSL/media/wsl-gui-screenshot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/wsl-gui-screenshot.png -------------------------------------------------------------------------------- /WSL/media/wsl-icon.svg: -------------------------------------------------------------------------------- 1 | 2 | 4 | 7 | 8 | 10 | 22 | 24 | 27 | 31 | 32 | 33 | -------------------------------------------------------------------------------- /WSL/media/wsl-install.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/wsl-install.png -------------------------------------------------------------------------------- /WSL/media/wsl-open-vs-code.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/wsl-open-vs-code.gif -------------------------------------------------------------------------------- /WSL/media/wsl-opensource.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/wsl-opensource.png -------------------------------------------------------------------------------- /WSL/media/wsl2-network-l2w.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/wsl2-network-l2w.png -------------------------------------------------------------------------------- /WSL/media/wsl2-network-w2l.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/wsl2-network-w2l.jpg -------------------------------------------------------------------------------- /WSL/media/wslmountsimple.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/wslmountsimple.png -------------------------------------------------------------------------------- /WSL/media/wslmountvhd.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/WSL/272b09b851d43e4303d5d3e229b589e4f361ba87/WSL/media/wslmountvhd.png -------------------------------------------------------------------------------- /WSL/networking.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Accessing network applications with WSL 3 | description: Learn about the considerations for accessing network applications when using Windows Subsystem for Linux (WSL). 4 | keywords: wsl, Linux, Windows, networking, ip address, ip addr, host IP, server, network, localhost, local area network, lan, ipv6, remote 5 | ms.date: 07/16/2024 6 | ms.topic: article 7 | --- 8 | 9 | # Accessing network applications with WSL 10 | 11 | There are a few considerations to be aware of when working with networking apps and WSL. By default WSL uses a [NAT based architecture](#default-networking-mode-nat), and we recommend trying the new [Mirrored networking mode](#mirrored-mode-networking) to get the latest features and improvements. 12 | 13 | ### Identify IP address 14 | 15 | There are two scenarios to consider when identifying the IP address used for a Linux distribution running via WSL: 16 | 17 | **Scenario One:** From the perspective of the Windows host, you want to query a Linux distribution's IP address running via WSL2, so that a program on Windows host can connect to a server program running inside the distribution (instance). 18 | 19 | The Windows host can use command: 20 | 21 | ``` 22 | wsl -d hostname -I 23 | ``` 24 | 25 | If querying the default distribution, this part of the command designating the distribution can be omitted: `-d `. Be sure to use a capital `-I` flag and not a lower-case `-i`. 26 | 27 | Under the hood, host command `wsl.exe` launches the target instance and executes Linux command `hostname -I` (short notation for `--all-ip-addresses`). This command then prints the IP address of the WSL instance to `STDOUT`. The `STDOUT` text content is then relayed back to wsl.exe. Finally, wsl.exe displays that output to the command line. 28 | 29 | A typical output might be: 30 | 31 | ```powershell 32 | 172.30.98.229 33 | ``` 34 | 35 | **Scenario Two:** A program running inside a Linux distribution via WSL2 (instance) wants to know the Windows host's IP address, so that a Linux program can connect to a Windows host server program. 36 | 37 | The WSL2 Linux user can use command: 38 | 39 | ```bash 40 | ip route show | grep -i default | awk '{ print $3}' 41 | ``` 42 | 43 | A typical output might be: 44 | 45 | ``` 46 | 172.30.96.1 47 | ``` 48 | 49 | So the `172.30.96.1` is the host IP address for Windows, in this example. 50 | 51 | > [!NOTE] 52 | > These above IP address querying action is typically required when WSL2 is running with the default [NAT network mode](#default-networking-mode-nat). 53 | > When the WSL2 is running with the new [mirrored mode](#mirrored-mode-networking), the Windows host and WSL2 VM can connect to each other using `localhost` (127.0.0.1) as the destination address, so the trick of using a query peer's IP address is not required. 54 | 55 | ## Default networking mode: NAT 56 | 57 | By default, WSL uses a NAT (Network Address Translation) based architecture for networking. Keep the following considerations in mind when working with a NAT-based networking architecture: 58 | 59 | ### Accessing Linux networking apps from Windows (localhost) 60 | 61 | If you are building a networking app (for example an app running on a NodeJS or SQL server) in your Linux distribution, you can access it from a Windows app (like your Edge or Chrome internet browser) using `localhost` (just like you normally would). 62 | 63 | ### Accessing Windows networking apps from Linux (host IP) 64 | 65 | If you want to access a networking app running on Windows (for example an app running on a NodeJS or SQL server) from your Linux distribution (ie Ubuntu), then you need to use the IP address of your host machine. While this is not a common scenario, you can follow these steps to make it work. 66 | 67 | 1. Obtain the IP address of your host machine by running this command from your Linux distribution: 68 | ```bash 69 | ip route show | grep -i default | awk '{ print $3}' 70 | ``` 71 | 2. Connect to any Windows server using the copied IP address. 72 | 73 | The picture below shows an example of this by connecting to a Node.js server running in Windows via curl. 74 | 75 | ![Connect to NodeJS server in Windows via Curl](media/wsl2-network-l2w.png) 76 | 77 | ### Connecting via remote IP addresses 78 | 79 | When using remote IP addresses to connect to your applications, they will be treated as connections from the Local Area Network (LAN). This means that you will need to make sure your application can accept LAN connections. 80 | 81 | For example, you may need to bind your application to `0.0.0.0` instead of `127.0.0.1`. In the example of a Python app using Flask, this can be done with the command: `app.run(host='0.0.0.0')`. Keep security in mind when making these changes as this will allow connections from your LAN. 82 | 83 | ### Accessing a WSL 2 distribution from your local area network (LAN) 84 | 85 | When using a WSL 1 distribution, if your computer was set up to be accessed by your LAN, then applications run in WSL could be accessed on your LAN as well. 86 | 87 | This isn't the default case in WSL 2. WSL 2 has a virtualized ethernet adapter with its own unique IP address. Currently, to enable this workflow you will need to go through the same steps as you would for a regular virtual machine. (We are looking into ways to improve this experience.) 88 | 89 | Here's an example of using the [Netsh interface portproxy](/windows-server/networking/technologies/netsh/netsh-interface-portproxy) Windows command to add a port proxy that listens on your host port and connects that port proxy to the IP address for the WSL 2 VM. 90 | 91 | ```powershell 92 | netsh interface portproxy add v4tov4 listenport= listenaddress=0.0.0.0 connectport= connectaddress=(wsl hostname -I) 93 | ``` 94 | 95 | In this example, you will need to update `` to a port number, for example `listenport=4000`. `listenaddress=0.0.0.0` means that incoming requests will be accepted from ANY IP address. The Listen Address specifies the IPv4 address for which to listen and can be changed to values that include: IP address, computer NetBIOS name, or computer DNS name. If an address isn't specified, the default is the local computer. You need to update the `` value to a port number where you want WSL to connect, for example `connectport=4000`. Lastly, the `connectaddress` value needs to be the IP address of your Linux distribution installed via WSL 2 (the WSL 2 VM address), which can be found by entering the command: `wsl.exe hostname -I`. 96 | 97 | So this command may look something like: 98 | 99 | ```powershell 100 | netsh interface portproxy add v4tov4 listenport=4000 listenaddress=0.0.0.0 connectport=4000 connectaddress=192.168.101.100 101 | ``` 102 | 103 | To obtain the IP address, use: 104 | 105 | - `wsl hostname -I` for the IP address of your Linux distribution installed via WSL 2 (the WSL 2 VM address) 106 | - `cat /etc/resolv.conf` for the IP address of the Windows machine as seen from WSL 2 (the WSL 2 VM) 107 | 108 | Using `listenaddress=0.0.0.0` will listen on all [IPv4 ports](https://stackoverflow.com/questions/9987409/want-to-know-what-is-ipv4-and-ipv6#:~:text=The%20basic%20difference%20is%20the,whereas%20IPv6%20has%20128%20bits.). 109 | 110 | > [!NOTE] 111 | > Using a lowercase "i" with the hostname command will generate a different result than using an uppercase "I". `wsl hostname -i` is your local machine (127.0.1.1 is a placeholder diagnostic address), whereas `wsl hostname -I` will return your local machine's IP address as seen by other machines and should be used to identify the `connectaddress` of your Linux distribution running via WSL 2. 112 | 113 | ## IPv6 access 114 | 115 | - `wsl hostname -i` for the IP address of your Linux distribution installed via WSL 2 (the WSL 2 VM address) 116 | - `ip route show | grep -i default | awk '{ print $3}'` for the IP address of the Windows machine as seen from WSL 2 (the WSL 2 VM) 117 | 118 | Using `listenaddress=0.0.0.0` will listen on all [IPv4 ports](https://stackoverflow.com/questions/9987409/want-to-know-what-is-ipv4-and-ipv6#:~:text=The%20basic%20difference%20is%20the,whereas%20IPv6%20has%20128%20bits.). 119 | 120 | ## Mirrored mode networking 121 | 122 | On machines running Windows 11 22H2 and higher you can [set `networkingMode=mirrored` under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-settings-for-wslconfig) to enable mirrored mode networking. Enabling this changes WSL to an entirely new networking architecture which has the goal of 'mirroring' the network interfaces that you have on Windows into Linux, to add new networking features and improve compatibility. 123 | 124 | Here are the current benefits to enabling this mode: 125 | 126 | - IPv6 support 127 | - Connect to Windows servers from within Linux using the localhost address `127.0.0.1`. IPv6 localhost address `::1` is not supported 128 | - Improved networking compatibility for VPNs 129 | - Multicast support 130 | - Connect to WSL directly from your local area network (LAN) 131 | 132 | > [!NOTE] 133 | > Run the following command in PowerShell window with admin privileges to [Configure Hyper-V firewall](/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall) settings to allow inbound connections: `Set-NetFirewallHyperVVMSetting -Name '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -DefaultInboundAction Allow` or `New-NetFirewallHyperVRule -Name "MyWebServer" -DisplayName "My Web Server" -Direction Inbound -VMCreatorId '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -Protocol TCP -LocalPorts 80`. 134 | 135 | This new mode addresses networking issues seen with using a NAT (Network Address Translation) based architecture. Find known issues or file feedback on any bugs identified in the [WSL product repo on GitHub](https://github.com/microsoft/wsl). 136 | 137 | ## DNS Tunneling 138 | 139 | On machines running Windows 11 22H2 and higher, setting [`dnsTunneling=true` under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-settings-for-wslconfig) has WSL use a virtualization feature to answer DNS requests from within WSL, instead of requesting them over a networking packet. This feature is aimed to improve compatibility with VPNs, and other complex networking set ups. 140 | 141 | ## Auto Proxy 142 | 143 | On machines running Windows 11 22H2 and higher, setting [`autoProxy=true` under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-settings-for-wslconfig) enforces WSL to use Windows' HTTP proxy information. If you have a proxy already set up in Windows, enabling this feature will make that proxy be set automatically in WSL as well. 144 | 145 | ## WSL and firewall 146 | 147 | On machines running Windows 11 22H2 and higher, with WSL 2.0.9 and higher, the Hyper-V firewall feature will be turned on by default. This will ensure that: 148 | 149 | - See [Windows Defender Firewall with Advanced Security](/windows/security/operating-system-security/network-security/windows-firewall/windows-firewall-with-advanced-security) to learn more about Windows security features that will automatically apply to WSL. 150 | - See [Configure Hyper-V firewall](/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall) to learn more about applying these rules and settings both locally and via online tools like Intune. 151 | -------------------------------------------------------------------------------- /WSL/opensource.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Open Source WSL 3 | description: Windows Subsystem for Linux is now Open Source. Learn what this means and how to download WSL and build it from source code. 4 | ms.date: 05/19/2025 5 | ms.topic: article 6 | --- 7 | 8 | # WSL and Open Source resources 9 | 10 | Windows Subsystem for Linux (WSL) is now Open Source. 11 | 12 | The code that powers WSL is available at [GitHub: microsoft/WSL Releases](https://github.com/microsoft/WSL/releases/). 13 | 14 | Learn what this means, how to download WSL, build from source code, and overview of WSL components, and more. 15 | 16 | ## Component overview 17 | 18 | WSL is made of a set of distribution components. Some run in Windows, and some run inside the WSL 2 virtual machine. 19 | 20 | :::image type="content" source="./media/wsl-architecture.png" alt-text="Overview diagram of WSL architecture."::: 21 | 22 | WSL’s code can be broken up into these main areas: 23 | 24 | - Command line executables that are the entry points to interact with WSL: `wsl.exe`, `wslconfig.exe`, and `wslg.exe`. These are processes run from `C:\\Windows\System32\wsl.exe` > `CreateProcess()`. 25 | 26 | - The WSL service that starts the WSL Virtual Machine (VM), starts the installed Linux distributions, mounts file access shares and more: `wslservice.exe`. 27 | 28 | - Linux init and daemon processes, binaries that run in Linux to provide WSL functionality: `init` for start up, `gns` for networking, `localhost` for port forwarding, etc. 29 | 30 | - File sharing Linux files to Windows with WSL’s plan9 server implementation: `plan9`. 31 | 32 | Learn more about each component at the WSL Open Source docs site: [wsl.dev](https://wsl.dev). 33 | 34 | The WSL source code is supported by these additional open sourced components: 35 | 36 | - [microsoft/wslg: Enabling the Windows Subsystem for Linux to include support for Wayland and X server related scenarios](https://github.com/microsoft/wslg): The Graphical User Interface (GUI) to run Linux apps with a UI (not just in the command line). 37 | - [microsoft/WSL2-Linux-Kernel: The source for the Linux kernel used in Windows Subsystem for Linux 2 (WSL2)](https://github.com/microsoft/WSL2-Linux-Kernel): The WSL2 Linux kernel. 38 | 39 | The following components are still part of the Windows image and are not open sourced at this time: 40 | 41 | - `Lxcore.sys`: the kernel side driver that powers WSL 1 42 | - `P9rdr.sys` and `p9np.dll`: The components which run the `\\wsl.localhost` filesystem redirection (from Windows to Linux) 43 | 44 | For more about the history and community behind open sourcing WSL, see the blog announcement from Microsoft Build 2025: [The Windows Subsystem for Linux is now open source by Pierre Boulay](https://blogs.windows.com/windowsdeveloper/2025/05/19/the-windows-subsystem-for-linux-is-now-open-source/) 45 | 46 | Visit the WSL repo on GitHub to contribute: [github.com/WSL]](https://github.com/microsoft/WSL/). 47 | -------------------------------------------------------------------------------- /WSL/store-release-notes.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Release Notes for WSL in the Microsoft Store 3 | description: Release notes for the Windows Subsystem for Linux 4 | keywords: release notes, wsl, windows, windows subsystem for linux, windowssubsystem, ubuntu, kernel 5 | ms.date: 10/11/2021 6 | ms.topic: article 7 | --- 8 | 9 | # Release Notes for Windows Subsystem for Linux in the Microsoft Store 10 | 11 | The release notes for [WSL inside of the Microsoft Store](https://aka.ms/wslstorepage) can be found on the [Microsoft/WSL GitHub repository releases page](https://github.com/microsoft/WSL/releases). Please see that list for latest updates. 12 | 13 | ## Known Issues: 14 | * Launching Windows Subsystem for Linux from session zero does not currently work (for example from an ssh connection). 15 | -------------------------------------------------------------------------------- /WSL/systemd.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Use systemd to manage Linux services with WSL 3 | description: Learn how to use systemd to manage Linux services with Windows Subsystem for Linux. 4 | ms.date: 01/13/2025 5 | ms.topic: article 6 | --- 7 | 8 | # Use systemd to manage Linux services with WSL 9 | 10 | Windows Subsystem for Linux (WSL) now supports systemd, an init system and service manager used by many popular Linux distributions such as Ubuntu, Debian, and more. ([What is systemd?](#what-is-systemd-in-linux)). 11 | 12 | The init system default has recently changed from SystemV, with [systemd now the default for the current version of Ubuntu](https://canonical.com/blog/ubuntu-desktop-23-04-release-roundup#:~:text=Systemd%20becomes%20the%20default%20for%20Ubuntu%20on%20WSL) that will be installed using the [`wsl --install` command](./install.md) default. Linux distributions other than the current version of Ubuntu may still use the WSL init, similar to SystemV init. To change to systemd, see [How to enable systemd](#how-to-enable-systemd). 13 | 14 | ## What is systemd in Linux? 15 | 16 | According to [systemd.io](https://systemd.io): "systemd is a suite of basic building blocks for a Linux system. It provides a system and service manager that runs as PID 1 and starts the rest of the system." 17 | 18 | Primarily an init system and service manager, systemd includes features like on-demand starting of daemons, mount and automount point maintenance, snapshot support, and processes tracking using Linux control groups. 19 | 20 | Most major Linux distributions now run systemd, so enabling it on WSL brings the experience even closer to using bare-metal Linux. See the [video announcement with systemd demos](#systemd-demo-video) or [examples of using systemd](#systemd-examples) below to learn more about what systemd has to offer. 21 | 22 | ## How to enable systemd? 23 | 24 | Systemd is [now the default for the current version of Ubuntu](https://canonical.com/blog/ubuntu-desktop-23-04-release-roundup#:~:text=Systemd%20becomes%20the%20default%20for%20Ubuntu%20on%20WSL) that will be installed using the [`wsl --install` command](./install.md) default. 25 | 26 | To enable systemd for any other Linux distributions running on WSL 2 (changing the default from using the systemv init): 27 | 28 | 1. Ensure that your WSL version is 0.67.6 or newer: 29 | 30 | - to check, run `wsl --version`; if the command throws `Invalid command line option: --version` error, you must update WSL; 31 | - to update, run `wsl --update` or [download the latest version from the Microsoft Store](https://aka.ms/wslstorepage). 32 | 33 | 2. Open a command line for your Linux distribution and enter `cd /` to access the root directory, then `ls` to list the files. You will see a directory named "etc" that contains the WSL configuration file for the distribution. Open this file so that you can make an update with the Nano text editor by entering: `nano /etc/wsl.conf`. 34 | 35 | 3. Add these lines in the `wsl.conf` file that you now have open to change the init used to systemd: 36 | 37 | ```bash 38 | [boot] 39 | systemd=true 40 | ``` 41 | 42 | ![Enable systemd on WSL 2](media/systemd-enable.png) 43 | 44 | 4. Exit the Nano text editor (Ctrl + X, type Y to save your change and confirm with the `enter` key). 45 | 46 | 5. You will then need to close the Linux distribution. You can use the command `wsl.exe --shutdown` in PowerShell to restart all WSL instances. 47 | 48 | 6. Once you restart the Linux distribution, systemd will be running. You can verify it by using the command `systemctl status` to show the _running_ state and the command `systemctl list-unit-files --type=service`, which will show the status of any services associated with your Linux distribution. 49 | 50 | If your Linux distribution is Debian/Ubuntu/Kali Rolling, you should not only have installed the systemd package, but also make sure the systemd-sysv package is installed. 51 | 52 | ```bash 53 | sudo apt-get update -y && sudo apt-get install systemd systemd-sysv -y 54 | ``` 55 | 56 | Learn more about [Advanced settings configuration in WSL](wsl-config.md), including the difference between the `wsl.conf` (distribution-specific) and `.wslconfig` (global) config files, how to update automount settings, etc. 57 | 58 | ## Systemd demo video 59 | 60 | Microsoft partnered with Canonical to bring systemd support to WSL. See Craig Loewen (PM for WSL at Microsoft) and Oliver Smith (PM for Ubuntu on WSL at Canonical) announce systemd support and show some demos of what it enables. 61 | 62 | > [!VIDEO https://learn-video.azurefd.net/vod/player?show=tabs-vs-spaces&ep=wsl-partnering-with-canonical-to-support-systemd] 63 | 64 | - [Systemd support blog announcement](https://devblogs.microsoft.com/commandline/systemd-support-is-now-available-in-wsl/) 65 | 66 | - [Oliver's tutorials based on these demos on the Ubuntu blog](https://ubuntu.com/blog/ubuntu-wsl-enable-systemd) - includes "Use snap to create a Nextcloud instance in minutes on WSL", "Manage your web projects with LXD", and ["Run a .Net Echo Bot as a systemd service on Ubuntu WSL"](https://ubuntu.com/tutorials/run-dotnet-echo-bot-with-systemd-on-ubuntu-wsl#1-overview) 67 | 68 | - [Craig's microk8s demo on GitHub](https://github.com/craigloewen-msft/microk8sdemo) 69 | 70 | ## Systemd examples 71 | 72 | A few examples of Linux applications that depend on systemd are: 73 | 74 | - [snap](https://snapcraft.io/): a software packaging and deployment system developed by Canonical for operating systems that use the Linux kernel and the systemd init system. The packages are called "snaps", the command line tool for building snaps is called "Snapcraft", the central repository where snaps can be downloaded/installed is called the "Snap Store", and the daemon required to run snaps (download from the store, mount into place, confine, and run apps out of them) is called "snapd". The entire system is sometimes referred to as "snappy." Try running the command: `snap install spotify`. 75 | 76 | - [microk8s](https://microk8s.io/): an open-source, low-ops, minimal production Kubernetes that automates deployment, scaling, and management of containerized apps. Follow the instructions to [Install MicroK8s on WSL2](https://microk8s.io/docs/install-wsl2), check out the [Get Started Tutorial](https://microk8s.io/docs/getting-started), or watch the video on [Kubernetes on Windows with MicroK8s and WSL 2](https://ubuntu.com/blog/kubernetes-on-windows-with-microk8s-and-wsl-2). 77 | 78 | - [systemctl](https://www.linode.com/docs/guides/introduction-to-systemctl/): a command-line utility used to control and inspect systemd and to help you interact with services on your Linux distribution. Try the command: `systemctl list-units --type=service` to see which services are available and their status. 79 | 80 | A few related tutorials demonstrating ways to use systemd: 81 | 82 | - [Understanding and Using Systemd](https://www.linux.com/training-tutorials/understanding-and-using-systemd/) 83 | 84 | - [Systemd Essentials: Working with the Services, Units, and the Journal](https://www.digitalocean.com/community/tutorials/systemd-essentials-working-with-services-units-and-the-journal) 85 | 86 | - [How To Sandbox Processes With Systemd On Ubuntu 20.04](https://www.digitalocean.com/community/tutorials/how-to-sandbox-processes-with-systemd-on-ubuntu-20-04) 87 | 88 | ## How does enabling systemd affect WSL architecture? 89 | 90 | Enabling support for systemd required changes to the WSL architecture. As systemd requires PID 1, the WSL init process started within the Linux distribution becomes a child process of the systemd. Because the WSL init process is responsible for providing the infrastructure for communication between the Linux and Windows components, changing this hierarchy required rethinking some of the assumptions made with the WSL init process. Additional modifications had to be made to ensure a clean shutdown (as that shutdown is controlled by systemd now) and to have compatibility with [WSLg](tutorials/gui-apps.md), the component of WSL that runs Linux Graphical User Interfaces (GUIs), or the Linux apps that display in windows rather than the command line. 91 | 92 | It is also important to note that with these changes, systemd services will NOT keep your WSL instance alive. Your WSL instance will stay alive in the same way it did previous to this update, which you can read more about in this [Background Task Support blog post from 2017](https://devblogs.microsoft.com/commandline/background-task-support-in-wsl/). 93 | -------------------------------------------------------------------------------- /WSL/toc.yml: -------------------------------------------------------------------------------- 1 | - name: WSL Documentation 2 | href: index.md 3 | - name: Overview 4 | items: 5 | - name: What is WSL? 6 | href: about.md 7 | - name: Comparing WSL Versions 8 | href: compare-versions.md 9 | - name: Basic wsl commands 10 | href: basic-commands.md 11 | - name: WSL Open Source code 12 | href: opensource.md 13 | - name: Install 14 | items: 15 | - name: Install WSL 16 | href: install.md 17 | - name: Manual install steps for older versions 18 | href: install-manual.md 19 | - name: Install on Windows Server 20 | href: install-on-server.md 21 | - name: Tutorials 22 | items: 23 | - name: Best practices for set up 24 | href: setup/environment.md 25 | - name: Get started with VS Code 26 | href: tutorials/wsl-vscode.md 27 | - name: Get started with Git 28 | href: tutorials/wsl-git.md 29 | - name: Get started with databases 30 | href: tutorials/wsl-database.md 31 | - name: Get started with Docker remote containers 32 | href: tutorials/wsl-containers.md 33 | - name: Get started with Visual Studio for C++ development 34 | href: /cpp/build/walkthrough-build-debug-wsl2 35 | - name: Set up GPU acceleration (NVIDIA CUDA/DirectML) 36 | href: tutorials/gpu-compute.md 37 | - name: Run Linux GUI apps 38 | href: tutorials/gui-apps.md 39 | - name: Install NodeJS on WSL 40 | href: /windows/dev-environment/javascript/nodejs-on-wsl 41 | - name: Get started with Linux and Bash 42 | href: tutorials/linux.md 43 | - name: Concepts 44 | items: 45 | - name: Working across file systems 46 | href: filesystems.md 47 | - name: Advanced settings configuration 48 | href: wsl-config.md 49 | - name: File access and permissions 50 | href: file-permissions.md 51 | - name: Networking considerations 52 | href: networking.md 53 | - name: Use systemd to manage services 54 | href: systemd.md 55 | - name: How-to 56 | items: 57 | - name: Import any Linux distribution 58 | href: use-custom-distro.md 59 | - name: Build a custom distribution 60 | href: build-custom-distro.md 61 | - name: Mount a disk in WSL 2 62 | href: wsl2-mount-disk.md 63 | - name: Connect USB devices 64 | href: connect-usb.md 65 | - name: Adjust case sensitivity 66 | href: case-sensitivity.md 67 | - name: Manage available disk space 68 | href: disk-space.md 69 | - name: Create WSL plugins 70 | href: wsl-plugins.md 71 | - name: Enterprise security 72 | items: 73 | - name: Set up WSL for your company 74 | href: enterprise.md 75 | - name: Intune settings for WSL 76 | href: intune.md 77 | - name: Frequently Asked Questions 78 | href: faq.yml 79 | - name: Troubleshooting 80 | href: troubleshooting.md 81 | - name : Release Notes 82 | items: 83 | - name: General Release Notes 84 | href: release-notes.md 85 | - name: Linux kernel Release Notes 86 | href: kernel-release-notes.md 87 | - name: Microsoft Store Release Notes 88 | href: store-release-notes.md 89 | -------------------------------------------------------------------------------- /WSL/tutorials/gpu-compute.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: GPU accelerated ML training in WSL 3 | description: Learn how to setup the Windows Subsystem for Linux with NVIDIA CUDA, TensorFlow-DirectML, and PyTorch-DirectML. Read about using GPU acceleration with WSL to support machine learning training scenarios. 4 | ms.date: 11/19/2024 5 | ms.topic: article 6 | --- 7 | 8 | # Get started with GPU acceleration for ML in WSL 9 | 10 | Machine learning (ML) is becoming a key part of many development workflows. Whether you're a data scientist, ML engineer, or starting your learning journey with ML the Windows Subsystem for Linux (WSL) offers a great environment to run the most common and popular GPU accelerated ML tools. 11 | 12 | There are lots of different ways to set up these tools. For example, [NVIDIA CUDA in WSL](https://developer.nvidia.com/cuda/wsl), [TensorFlow-DirectML](https://pypi.org/project/tensorflow-directml/) and [PyTorch-DirectML](https://pypi.org/project/pytorch-directml/) all offer different ways you can use your GPU for ML with WSL. To learn more about the reasons for choosing one versus another, see [GPU accelerated ML training](/windows/ai/directml/gpu-accelerated-training). 13 | 14 | This guide will show how to set up: 15 | 16 | * NVIDIA CUDA if you have an NVIDIA graphics card and run a sample ML framework container 17 | * TensorFlow-DirectML and PyTorch-DirectML on your AMD, Intel, or NVIDIA graphics card 18 | 19 | ## Prerequisites 20 | 21 | * Ensure you are running [Windows 11](https://microsoft.com/software-download/windows11) or [Windows 10, version 21H2](https://microsoft.com/software-download/windows10) or higher. 22 | * [Install WSL and set up a username and password for your Linux distribution](/windows/wsl/install). 23 | 24 | ## Set up NVIDIA CUDA with Docker 25 | 26 | 1. [Download and install the latest driver for your NVIDIA GPU](https://www.nvidia.com/Download/index.aspx) 27 | 2. Install [Docker Desktop](/windows/wsl/tutorials/wsl-containers#install-docker-desktop) or install the Docker engine directly in WSL by running the following command 28 | 29 | ```bash 30 | curl https://get.docker.com | sh 31 | ```` 32 | 33 | ```bash 34 | sudo service docker start 35 | ```` 36 | 37 | 3. If you installed the Docker engine directly then [install the NVIDIA Container Toolkit](https://docs.nvidia.com/cuda/wsl-user-guide/index.html#ch04-sub02-install-nvidia-docker) following the steps below. 38 | 39 | Set up the stable repository for the NVIDIA Container Toolkit by running the following commands: 40 | 41 | ```bash 42 | distribution=$(. /etc/os-release;echo $ID$VERSION_ID) 43 | ``` 44 | 45 | ```bash 46 | curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-docker-keyring.gpg 47 | ``` 48 | 49 | ```bash 50 | curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-docker-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-docker.list 51 | ``` 52 | 53 | Install the NVIDIA runtime packages and dependencies by running the commands: 54 | 55 | ```bash 56 | sudo apt-get update 57 | ``` 58 | 59 | ```bash 60 | sudo apt-get install -y nvidia-docker2 61 | ``` 62 | 63 | 4. Run a machine learning framework container and sample. 64 | 65 | To run a machine learning framework container and start using your GPU with this NVIDIA NGC TensorFlow container, enter the command: 66 | 67 | ````bash 68 | docker run --gpus all -it --shm-size=1g --ulimit memlock=-1 --ulimit stack=67108864 nvcr.io/nvidia/tensorflow:20.03-tf2-py3 69 | ```` 70 | 71 | ![TensorFlow with CUDA running inside a Docker container](https://user-images.githubusercontent.com/2146704/165866792-0fc1b9f6-a7be-49e2-8eb4-919a9b13a07c.png) 72 | 73 | You can run a pre-trained model sample that is built into this container by running the commands: 74 | 75 | ```bash 76 | cd nvidia-examples/cnn/ 77 | ``` 78 | 79 | ```bash 80 | python resnet.py --batch_size=64 81 | ``` 82 | 83 | ![TensorFlow sample model training within Docker container](https://user-images.githubusercontent.com/2146704/165867329-fae2f8ec-e86d-412e-9e2c-dcfec0ec2429.gif) 84 | 85 | 86 | Additional ways to get setup and utilize NVIDIA CUDA can be found in the [NVIDIA CUDA on WSL User Guide](https://docs.nvidia.com/cuda/wsl-user-guide/index.html#getting-started-with-cuda-on-wsl). 87 | 88 | ## Set up TensorFlow-DirectML or PyTorch-DirectML 89 | 90 | 1. Download and install the latest driver from your GPU vendors website: [AMD](https://www.amd.com/en/support), [Intel](https://www.intel.com/content/www/us/en/download/19344/intel-graphics-windows-dch-drivers.html), or [NVIDIA](https://www.nvidia.com/Download/index.aspx). 91 | 92 | 2. Setup a Python environment. 93 | 94 | We recommend setting up a virtual Python environment. There are many tools you can use to setup a virtual Python environment — for these instructions, we'll use [Anaconda's Miniconda](https://docs.conda.io/en/latest/miniconda.html). 95 | 96 | ```bash 97 | wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh 98 | ``` 99 | 100 | ```bash 101 | bash Miniconda3-latest-Linux-x86_64.sh 102 | ``` 103 | 104 | ```bash 105 | conda create --name directml python=3.7 -y 106 | ``` 107 | 108 | ```bash 109 | conda activate directml 110 | ``` 111 | 112 | 3. Install the machine learning framework backed by DirectML of your choice. 113 | 114 | TensorFlow-DirectML: 115 | 116 | ```bash 117 | pip install tensorflow-directml 118 | ``` 119 | 120 | PyTorch-DirectML: 121 | 122 | ```bash 123 | sudo apt install libblas3 libomp5 liblapack3 124 | ``` 125 | 126 | ```bash 127 | pip install torch-directml 128 | ``` 129 | 130 | 4. Run a quick addition sample in an interactive Python session for [TensorFlow-DirectML](/windows/ai/directml/gpu-tensorflow-wsl#install-the-tensorflow-with-directml-package) or [PyTorch-DirectML](/windows/ai/directml/gpu-pytorch-wsl#install-the-pytorch-with-directml-package) to make sure everything is working. 131 | 132 | If you have questions or run into issues, visit the [DirectML repo on GitHub](https://github.com/microsoft/DirectML#feedback). 133 | 134 | ## Multiple GPUs 135 | 136 | If you have multiple GPUs on your machine you can also access them inside of WSL. However, you will only be able to access one at a time. To choose a specific GPU please set the environment variable below to the name of your GPU as it appears in device manager: 137 | 138 | ```bash 139 | export MESA_D3D12_DEFAULT_ADAPTER_NAME="" 140 | ``` 141 | 142 | This will do a string match, so if you set it to "NVIDIA" it will match the first GPU that starts with "NVIDIA". 143 | 144 | ## Additional Resources 145 | 146 | * [Guidance for setting up NVIDIA CUDA in WSL](https://docs.nvidia.com/cuda/wsl-user-guide/index.html) 147 | * [Guidance for setting up TensorFlow with DirectML in WSL](/windows/ai/directml/gpu-tensorflow-wsl) 148 | * [TensorFlow with DirectML Samples](https://github.com/microsoft/DirectML/tree/master/TensorFlow) 149 | * [Guidance for setting up PyTorch with DirectML in WSL](/windows/ai/directml/gpu-pytorch-wsl) 150 | * [PyTorch with DirectML Samples](https://github.com/microsoft/DirectML/tree/master/PyTorch) 151 | -------------------------------------------------------------------------------- /WSL/tutorials/gui-apps.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Run Linux GUI apps with WSL 3 | description: Learn how WSL support running Linux GUI apps. 4 | ms.date: 01/04/2024 5 | ms.topic: article 6 | --- 7 | 8 | # Run Linux GUI apps on the Windows Subsystem for Linux 9 | 10 | Windows Subsystem for Linux (WSL) now supports running Linux GUI applications (X11 and Wayland) on Windows in a fully integrated desktop experience. 11 | 12 | WSL 2 enables Linux GUI applications to feel native and natural to use on Windows. 13 | 14 | - Launch Linux apps from the Windows Start menu 15 | - Pin Linux apps to the Windows task bar 16 | - Use alt-tab to switch between Linux and Windows apps 17 | - Cut + Paste across Windows and Linux apps 18 | 19 | You can now integrate both Windows and Linux applications into your workflow for a seamless desktop experience. 20 | 21 | ![Screenshot of Linux and Windows apps open on a desktop](../media/wsl-gui-screenshot.png) 22 | 23 | ## Install support for Linux GUI apps 24 | 25 | ### Prerequisites 26 | 27 | - You will need to be on **Windows 10 Build 19044+** or **Windows 11** to access this feature. 28 | 29 | - **Installed driver for vGPU** 30 | 31 | To run Linux GUI apps, you should first install the driver matching your system below. This will enable you to use a virtual GPU (vGPU) so you can benefit from hardware accelerated OpenGL rendering. 32 | 33 | - [**Intel** GPU driver](https://www.intel.com/content/www/us/en/download/19344/intel-graphics-windows-dch-drivers.html) 34 | - [**AMD** GPU driver](https://www.amd.com/en/support) 35 | - [**NVIDIA** GPU driver](https://www.nvidia.com/Download/index.aspx?lang=en-us) 36 | 37 | ### Fresh install - No prior WSL installation 38 | 39 | You can now install everything you need to run Windows Subsystem for Linux (WSL) by entering this command in an administrator PowerShell or Windows Command Prompt and then restarting your machine. 40 | 41 | ```powershell 42 | wsl --install 43 | ``` 44 | 45 | Once your machine has finished rebooting, installation will continue and you will be asked to enter a username and password. This will be your Linux credential for the Ubuntu distribution. 46 | 47 | You're now ready to begin using Linux GUI apps on WSL! 48 | 49 | For more info check [install WSL](../install.md). 50 | 51 | ### Existing WSL install 52 | 53 | If you already have WSL installed on your machine, you can update to the latest version that includes Linux GUI support by running the update command from an elevated command prompt. 54 | 55 | 1. Select **Start**, type **PowerShell**, right-click **Windows PowerShell**, and then select **Run as administrator**. 56 | 57 | 2. Enter the WSL update command: 58 | 59 | ```powershell 60 | wsl --update 61 | ``` 62 | 63 | 3. You will need to restart WSL for the update to take effect. You can restart WSL by running the shutdown command in PowerShell. 64 | 65 | ```powershell 66 | wsl --shutdown 67 | ``` 68 | 69 | > [!NOTE] 70 | > Linux GUI apps are only supported with WSL 2 and will not work with a Linux distribution configured for WSL 1. Read about [how to change your distribution from WSL 1 to WSL 2](../basic-commands.md#set-wsl-version-to-1-or-2). 71 | 72 | ## Run Linux GUI apps 73 | 74 | You can run the following commands from your Linux terminal to download and install these popular Linux applications. If you are using a different distribution than Ubuntu, it may use a different package manager than apt. Once the Linux application is installed, you can find it in your **Start** menu under the distribution name. For example: `Ubuntu -> Microsoft Edge`. 75 | 76 | > [!NOTE] 77 | > Support for GUI apps on WSL does not provide a full desktop experience. It relies on Windows desktop, so installing desktop-focused tools or apps may not be supported. To request additional support, you can file an issue in the [WSLg repo on GitHub](https://github.com/microsoft/wslg/issues). 78 | 79 | ### Update the packages in your distribution 80 | 81 | ```bash 82 | sudo apt update 83 | ``` 84 | 85 | ### Install Gnome Text Editor 86 | 87 | Gnome Text Editor is the default text editor of the GNOME desktop environment. 88 | 89 | ```bash 90 | sudo apt install gnome-text-editor -y 91 | ``` 92 | 93 | To launch your bashrc file in the editor, enter: `gnome-text-editor ~/.bashrc` 94 | 95 | > [!NOTE] 96 | > [GNOME Text Editor](https://en.wikipedia.org/wiki/GNOME_Text_Editor) replaces gedit as GNOME/Ubuntu's default text editor in Ubuntu 22.10. If you're running an older version of Ubuntu and want to use [gedit](https://en.wikipedia.org/wiki/Gedit), the previous default text editor, use `sudo apt install gedit -y`. 97 | 98 | ### Install GIMP 99 | 100 | GIMP is a free and open-source raster graphics editor used for image manipulation and image editing, free-form drawing, transcoding between different image file formats, and more specialized tasks. 101 | 102 | ```bash 103 | sudo apt install gimp -y 104 | ``` 105 | 106 | To launch, enter: `gimp` 107 | 108 | ### Install Nautilus 109 | 110 | Nautilus, also known as GNOME Files, is the file manager for the GNOME desktop. (Similar to Windows File Explorer). 111 | 112 | ```bash 113 | sudo apt install nautilus -y 114 | ``` 115 | 116 | To launch, enter: `nautilus` 117 | 118 | ### Install VLC 119 | 120 | VLC is a free and open source cross-platform multimedia player and framework that plays most multimedia files. 121 | 122 | ```bash 123 | sudo apt install vlc -y 124 | ``` 125 | 126 | To launch, enter: `vlc` 127 | 128 | ### Install X11 apps 129 | 130 | X11 is the Linux windowing system and this is a miscellaneous collection of apps and tools that ship with it, such as the xclock, xcalc calculator, xclipboard for cut and paste, xev for event testing, etc. See the [x.org docs](https://www.x.org/wiki/UserDocumentation/GettingStarted/) for more info. 131 | 132 | ```bash 133 | sudo apt install x11-apps -y 134 | ``` 135 | 136 | To launch, enter the name of the tool you would like to use. For example: 137 | 138 | - `xcalc`, `xclock`, `xeyes` 139 | 140 | ### Install Google Chrome for Linux 141 | 142 | To install the Google Chrome for Linux: 143 | 144 | 1. Change directories into the temp folder: `cd /tmp` 145 | 2. Use wget to download it: `wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb` 146 | 3. Install the package: `sudo apt install --fix-missing ./google-chrome-stable_current_amd64.deb` 147 | 148 | *The `--fix-missing` option is used to fix missing dependencies that may arise during the installation process. The `./` in the command specifies the current directory where the .deb file is located. If the .deb file is located in a different directory, you will need to specify the path to the file in the command. 149 | 150 | To launch, enter: `google-chrome` 151 | 152 | ### Install Microsoft Edge browser for Linux 153 | 154 | Find information on how to [install the Microsoft Edge browser for Linux using the command line on the Edge Insider site](https://www.microsoftedgeinsider.com/download/?platform=linux-deb). Select **Get instructions** under the Command line installation section of the page. 155 | 156 | To launch, enter: `microsoft-edge` 157 | 158 | ## Troubleshooting 159 | 160 | If you have any problem starting GUI applications please check this guide first: [Diagnosing "cannot open display" type issues with WSLg](https://github.com/microsoft/wslg/wiki/Diagnosing-%22cannot-open-display%22-type-issues-with-WSLg) 161 | -------------------------------------------------------------------------------- /WSL/tutorials/linux.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Get started with Linux using WSL 3 | description: Learn some basics for working with Linux and a Bash command line using WSL. 4 | ms.date: 08/05/2022 5 | ms.topic: article 6 | --- 7 | 8 | # Getting started with Linux and Bash 9 | 10 | This tutorial will help those new to Linux to get started installing and updating packages using the Ubuntu distribution of Linux that is installed by default using WSL, as well as using some basic commands with the Bash command line. 11 | 12 | ## Installing and Updating Software 13 | 14 | You can install and update software programs directly from the command line using the preferred package manager for the distribution you are running. 15 | 16 | In Ubuntu, for example, first update the list of software available by running ‘sudo apt update’. Then, you can directly get software by using the ‘sudo apt-get install’ command followed by the name of the program you wish to install: 17 | 18 | ```bash 19 | sudo apt-get install 20 | ``` 21 | 22 | To update programs that have already been installed, you can run: 23 | 24 | ```bash 25 | sudo apt update && sudo apt upgrade 26 | ``` 27 | ![upgrade_and_update](https://user-images.githubusercontent.com/98557455/183468063-35b00e76-d11a-4260-aa3c-9f8e0dab2e47.gif) 28 | 29 | > [!TIP] 30 | > Different distributions of Linux often have different package managers and will require using an install command specific to the associated package manager. For example, the main package manager for Arch Linux is called [pacman](https://wiki.archlinux.org/title/pacman) and the install command would be `sudo pacman -S `. The main package manager for OpenSuse is called [Zypper](https://doc.opensuse.org/documentation/leap/archive/42.2/reference/html/book.opensuse.reference/cha.sw_cl.html#sec.zypper) and the install command would be `sudo zypper install `. The main package manager for Alpine is called [apk](https://wiki.alpinelinux.org/wiki/Package_management) and the install command would be `sudo apk add `. The two main package managers for Red Hat distributions, like CentOS, are [YUM and RPM](https://www.redhat.com/sysadmin/how-manage-packages) and an install command could be `sudo yum install ` or `sudo rpo -i `. Refer to the documentation of the distribution you are working with to find out what tools are available for you to install and update software. 31 | 32 | ## Working with files and directories 33 | 34 | To view the path of the directory you are currently in, use the ‘pwd’ command: 35 | 36 | ```bash 37 | pwd 38 | ``` 39 | 40 | To create a new directory, use the ‘mkdir’ command followed by the name of the directory you want to create: 41 | 42 | ```bash 43 | mkdir hello_world 44 | ``` 45 | 46 | 47 | To change directories, use the ‘cd’ command followed by the name of the directory you want to navigate to: 48 | 49 | ```bash 50 | cd hello_world 51 | ``` 52 | 53 | To see the contents within the directory you are currently in, type ‘ls’ into the command line: 54 | 55 | ```bash 56 | ls 57 | ``` 58 | ![directory-and-file-commands1](https://user-images.githubusercontent.com/98557455/183470971-7b188fdd-bb01-44e0-ac17-56f246ffd78e.gif) 59 | 60 | By default, the ‘ls’ command will print the name of all the files and directories only. To get additional information such as the last time a file was modified or file permissions, use the flag “-l”: 61 | 62 | ```bash 63 | ls -l 64 | ``` 65 | 66 | 67 | You can create a new file via the ‘touch’ command followed by the name of the file you would like to create: 68 | 69 | ```bash 70 | touch hello_world.txt 71 | ``` 72 | You can edit files using any downloaded graphical text-editor or the VS Code Remote – WSL extension. You can learn more about getting started with VS Code [here](/windows/wsl/tutorials/wsl-vscode) 73 | 74 | If you prefer to edit a file directly from the command-line, you’ll need to use a command-line editor such as vim, emacs, or nano. Many distributions come with one or more of these programs installed, but you can always install these programs by following the installation instructions outlined in the guide from [above](https://github.com/MicrosoftDocs/WSL/edit/linux-tutorial/WSL/tutorials/linux.md#installing-and-updating-software). 75 | 76 | To edit your file with your preferred method of editing, simply run the program name followed by the name of the file you’d like to edit: 77 | 78 | ```bash 79 | code hello_world.txt 80 | ``` 81 | 82 | ```bash 83 | notepad.exe hello_world.txt 84 | ``` 85 | 86 | To see the contents of a file in the command line, use the ‘cat’ command followed by the file you’d like to read: 87 | 88 | ```bash 89 | cat hello_world.txt 90 | ``` 91 | 92 | ![directory-and-file-commands2](https://user-images.githubusercontent.com/98557455/183481394-25bc0b2f-3d6d-465f-8f0b-aa5393f88727.gif) 93 | 94 | ## Using Pipes and Redirect Operators 95 | 96 | A pipe ‘|’ redirects the output from one command as input into another command. For example, lhscmd | rhscmd would direct the output from lhscmd to rhscmd. Pipes can be used in a variety of ways to quickly accomplish tasks through the command line. Below are just a few simple examples of how pipes can be used. 97 | 98 | Imagine you want to quickly sort the contents of a file. Take the fruits.txt example below: 99 | 100 | ```bash 101 | cat fruits.txt 102 | 103 | Orange 104 | 105 | Banana 106 | 107 | Apple 108 | 109 | Pear 110 | 111 | Plum 112 | 113 | Kiwi 114 | 115 | Strawberry 116 | 117 | Peach 118 | ``` 119 | 120 | You can quickly sort this list by using a pipe: 121 | 122 | ```bash 123 | $ cat fruits.txt | sort 124 | 125 | Apple 126 | 127 | Banana 128 | 129 | Kiwi 130 | 131 | Orange 132 | 133 | Peach 134 | 135 | Pear 136 | 137 | Plum 138 | 139 | Strawberry 140 | ``` 141 | 142 | By default, the output of the ‘cat’ command is sent to standard output; however, the ‘|’ allows us to instead redirect the output as the input to another command, ‘sort’. 143 | 144 | Another use case is searching. You can use ‘grep’ which is a helpful command that searches input for a particular search string. 145 | 146 | ```bash 147 | cat fruits.txt | grep P 148 | 149 | Pear 150 | 151 | Plum 152 | 153 | Peach 154 | ``` 155 | 156 | You can also use redirect operators like ‘>’ to pass the output to a file or stream. For example, if you wanted to create a new .txt file with the sorted contents of fruit.txt: 157 | 158 | ```bash 159 | cat fruits.txt | sort > sorted_fruit.txt 160 | ``` 161 | 162 | ```bash 163 | $ cat sorted_fruit.txt 164 | 165 | Apple 166 | 167 | Banana 168 | 169 | Kiwi 170 | 171 | Orange 172 | 173 | Peach 174 | 175 | Pear 176 | 177 | Plum 178 | 179 | Strawberry 180 | ``` 181 | 182 | By default, the output of the sort command is sent to standard output; however, the ‘>’ operator allows us to instead redirect the output into a new file named sorted_fruits.txt. 183 | 184 | You can use pipes and redirect operators in many interesting ways to more efficiently complete tasks directly from the command line. 185 | 186 | ## Recommended content 187 | 188 | - [Microsoft Learn: Introduction to Bash](/learn/modules/bash-introduction/) 189 | 190 | - [Command Line for Beginners](https://ubuntu.com/tutorials/command-line-for-beginners#1-overview) 191 | 192 | - [Microsoft Learn: Get Started with WSL](/learn/modules/get-started-with-windows-subsystem-for-linux/) -------------------------------------------------------------------------------- /WSL/tutorials/wsl-git.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Get started using Git on WSL 3 | description: Learn how to set up Git for version control on the Windows Subsystem for Linux, along with Git Credential Manager. 4 | ms.date: 06/21/2023 5 | ms.topic: article 6 | --- 7 | 8 | # Get started using Git on Windows Subsystem for Linux 9 | 10 | Git is the most commonly used version control system. With Git, you can track changes you make to files, so you have a record of what has been done, and have the ability to revert to earlier versions of the files if needed. Git also makes collaboration easier, allowing changes by multiple people to all be merged into one source. 11 | 12 | ## Git can be installed on Windows AND on WSL 13 | 14 | An important consideration: when you enable WSL and install a Linux distribution, you are installing a new file system, separated from the Windows NTFS C:\ drive on your machine. In Linux, drives are not given letters. They are given mount points. The root of your file system `/` is the mount point of your root partition, or folder, in the case of WSL. Not everything under `/` is the same drive. For example, on my laptop, I've installed two version of Ubuntu (20.04 and 18.04), as well as Debian. If I open those distributions, select the home directory with the command `cd ~`, and then enter the command `explorer.exe .`, Windows File Explorer will open and show me the directory path for that distribution. 15 | 16 | | Linux distro | Windows Path to access home folder | 17 | | ----------- | ----------- | 18 | | Ubuntu 20.04 | `\\wsl$\Ubuntu-20.04\home\username` | 19 | | Ubuntu 18.04 | `\\wsl$\Ubuntu-18.04\home\username` | 20 | | Debian | `\\wsl$\Debian\home\username` | 21 | | Windows PowerShell | `C:\Users\username` | 22 | 23 | > [!TIP] 24 | > If you are seeking to access the Windows file directory from your WSL distribution command line, instead of `C:\Users\username`, the directory would be accessed using `/mnt/c/Users/username`, because the Linux distribution views your Windows file system as a mounted drive. 25 | 26 | You will need to install Git on each file system that you intend to use it with. 27 | 28 | ![Showing Git versions by distro](../media/git-versions.gif) 29 | 30 | ## Installing Git 31 | 32 | Git comes already installed with most of the Windows Subsystem for Linux distributions, however, you may want to update to the latest version. You also will need to set up your git config file. 33 | 34 | To install Git, see the [Git Download for Linux](https://git-scm.com/download/linux) site. Each Linux distribution has their own package manager and install command. 35 | 36 | For the latest stable Git version in Ubuntu/Debian, enter the command: 37 | 38 | ```bash 39 | sudo apt-get install git 40 | ``` 41 | 42 | > [!NOTE] 43 | > You also may want to [install Git for Windows](https://git-scm.com/download/win) if you haven't already. 44 | 45 | ## Git config file setup 46 | 47 | To set up your Git config file, open a command line for the distribution you're working in and set your name with this command (replacing "Your Name" with your preferred username): 48 | 49 | ```bash 50 | git config --global user.name "Your Name" 51 | ``` 52 | 53 | Set your email with this command (replacing "youremail@domain.com" with the email you prefer): 54 | 55 | ```bash 56 | git config --global user.email "youremail@domain.com" 57 | ``` 58 | 59 | > [!TIP] 60 | > If you don't yet have a GitHub account, you can [sign-up for one on GitHub](https://github.com/join). If you've never worked with Git before, [GitHub Guides](https://guides.github.com/) can help you get started. If you need to edit your Git config, you can do so with a built-in text editor like nano: `nano ~/.gitconfig`. 61 | 62 | We recommend that you [secure your account with two-factor authentication (2FA)](https://help.github.com/en/github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa). 63 | 64 | ## Git Credential Manager setup 65 | 66 | [Git Credential Manager (GCM)](https://github.com/GitCredentialManager/git-credential-manager) is a secure Git credential helper built on [.NET](https://dotnet.microsoft.com/) that can be used with both WSL1 and WSL2. It enables multi-factor authentication support for GitHub repos, [Azure DevOps](https://dev.azure.com/), Azure DevOps Server, and Bitbucket. 67 | 68 | GCM integrates into the authentication flow for services like GitHub and, once you're authenticated to your hosting provider, requests a new authentication token. It then stores the token securely in the [Windows Credential Manager](https://support.microsoft.com/help/4026814/windows-accessing-credential-manager). After the first time, you can use Git to talk to your hosting provider without needing to re-authenticate. It will just access the token in the Windows Credential Manager. 69 | 70 | In order to use GCM with WSL you must be on Windows 10 Version 1903 or later. This is the first version of Windows that includes the required `wsl.exe` tool that GCM uses to interoperate with Git in your WSL distributions. 71 | 72 | It is recommended to install the [latest Git for Windows](https://github.com/git-for-windows/git/releases/latest) in order to share credentials & settings between WSL and the Windows host. Git Credential Manager is included with Git for Windows and the latest version is included in each new Git for Windows release. During the installation, you will be asked to select a credential helper, with GCM set as the default. 73 | 74 | If you have a reason not to install Git for Windows, you can install GCM as a Linux application directly in your WSL distribution, but note that doing so means GCM is running as a Linux application and cannot utilize the authentication or credential storage features of the host Windows operating system. See the GCM repo for instructions on how to [configure WSL without Git for Windows](https://github.com/GitCredentialManager/git-credential-manager/blob/main/docs/wsl.md#configuring-wsl-without-git-for-windows). 75 | 76 | 77 | 78 | To set up GCM for use with a WSL distribution, open your distribution and enter this command: 79 | 80 | If GIT installed is >= v2.39.0 81 | 82 | ```bash 83 | git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe" 84 | ``` 85 | 86 | else if GIT installed is >= v2.36.1 87 | 88 | ```bash 89 | git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/libexec/git-core/git-credential-manager.exe" 90 | ``` 91 | 92 | else if version is < v2.36.1 enter this command: 93 | 94 | ```bash 95 | git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager-core.exe" 96 | ``` 97 | 98 | > [!NOTE] 99 | > Using GCM as a credential helper for a WSL Git installation means that any configuration set in WSL Git is NOT respected by GCM (by default). This is because GCM is running as a Windows application, and therefore will use the Git for Windows installation to query configuration. This means things like proxy settings for GCM need to be set in Git for Windows as well as WSL Git as they are stored in different files (`%USERPROFILE%\.gitconfig` vs `\\wsl$\distro\home\$USER\.gitconfig`). You can configure WSL so that GCM will use the WSL Git configuration, but this means that proxy settings will be unique to the specific WSL installation and not shared with others or the Windows host. 100 | 101 | ### Git with SSH 102 | 103 | Git Credential Manager only works with HTTP(S) remotes. You can still use Git with SSH: 104 | 105 | - [Azure DevOps SSH](/azure/devops/repos/git/use-ssh-keys-to-authenticate) 106 | - [GitHub SSH](https://help.github.com/en/articles/connecting-to-github-with-ssh) 107 | - [Bitbucket SSH](https://confluence.atlassian.com/bitbucket/ssh-keys-935365775.html) 108 | 109 | ### Additional configuration for Azure 110 | 111 | If you intend to work with [Azure Repos](https://github.com/GitCredentialManager/git-credential-manager/blob/main/docs/configuration.md#credentialprovider) or [Azure DevOps](https://github.com/GitCredentialManager/git-credential-manager/blob/main/docs/wsl.md#configuring-wsl-with-git-for-windows-recommended), some additional configuration is required: 112 | 113 | ```Bash 114 | git config --global credential.https://dev.azure.com.useHttpPath true 115 | ``` 116 | 117 | Now any git operation you perform within your WSL distribution will use GCM. If you already have credentials cached for a host, it will access them from the credential manager. If not, you'll receive a dialog response requesting your credentials, even if you're in a Linux console. 118 | 119 | > [!TIP] 120 | > If you are using a GPG key for code signing security, you may need to [associate your GPG key with your GitHub email](https://help.github.com/en/github/authenticating-to-github/associating-an-email-with-your-gpg-key). 121 | 122 | ## Adding a Git Ignore file 123 | 124 | We recommend adding a [.gitignore file](https://help.github.com/en/articles/ignoring-files) to your projects. GitHub offers [a collection of useful .gitignore templates](https://github.com/github/gitignore) with recommended .gitignore file setups organized according to your use-case. For example, here is [GitHub's default gitignore template for a Node.js project](https://github.com/github/gitignore/blob/master/Node.gitignore). 125 | 126 | If you choose to [create a new repo using the GitHub website](https://help.github.com/articles/create-a-repo), there are check boxes available to initialize your repo with a README file, .gitignore file set up for your specific project type, and options to add a license if you need one. 127 | 128 | ## Git and VS Code 129 | 130 | Visual Studio Code comes with built-in support for Git, including a source control tab that will show your changes and handle a variety of git commands for you. Learn more about [VS Code's Git support](https://code.visualstudio.com/docs/editor/versioncontrol#_git-support). 131 | 132 | ## Git line endings 133 | 134 | If you are working with the same repository folder between Windows, WSL, or a container, be sure to set up consistent line endings. 135 | 136 | Since Windows and Linux use different default line endings, Git may report a large number of modified files that have no differences aside from their line endings. To prevent this from happening, you can disable line ending conversion using a `.gitattributes` file or globally on the Windows side. See this [VS Code doc about resolving Git line ending issues](https://code.visualstudio.com/docs/remote/troubleshooting#_resolving-git-line-ending-issues-in-wsl-resulting-in-many-modified-files). 137 | 138 | ## Additional resources 139 | 140 | * [WSL & VS Code](./wsl-vscode.md) 141 | * [GitHub Learning Lab: Online courses](https://github.com/apps/github-learning-lab) 142 | * [Git Visualization Tool](http://git-school.github.io/visualizing-git/) 143 | * [Git Tools - Credential Storage](https://git-scm.com/book/it/v2/Git-Tools-Credential-Storage) 144 | -------------------------------------------------------------------------------- /WSL/tutorials/wsl-vscode.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Get started using VS Code with WSL 3 | description: Learn how to set up VS Code to author and debug code using the Windows Subsystem for Linux. 4 | keywords: wsl, windows, windowssubsystem, gnu, linux, bash, vs code, remote extension, debug, path, visual studio 5 | ms.date: 09/27/2021 6 | ms.topic: article 7 | --- 8 | 9 | # Get started using Visual Studio Code with Windows Subsystem for Linux 10 | 11 | Visual Studio Code, along with the WSL extension, enables you to use WSL as your full-time development environment directly from VS Code. You can: 12 | 13 | * develop in a Linux-based environment 14 | * use Linux-specific toolchains and utilities 15 | * run and debug your Linux-based applications from the comfort of Windows while maintaining access to productivity tools like Outlook and Office 16 | * use the VS Code built-in terminal to run your Linux distribution of choice 17 | * take advantage of VS Code features like [Intellisense code completion](https://code.visualstudio.com/docs/editor/intellisense), [linting](https://code.visualstudio.com/docs/python/linting), [debug support](https://code.visualstudio.com/docs/nodejs/nodejs-debugging), [code snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets), and [unit testing](https://code.visualstudio.com/docs/python/testing) 18 | * easily manage your version control with VS Code's built-in [Git support](https://code.visualstudio.com/docs/editor/versioncontrol#_git-support) 19 | * run commands and VS Code extensions directly on your WSL projects 20 | * edit files in your Linux or mounted Windows filesystem (for example /mnt/c) without worrying about pathing issues, binary compatibility, or other cross-OS challenges 21 | 22 | ## Install VS Code and the WSL extension 23 | 24 | * Visit the [VS Code install page](https://code.visualstudio.com/download) and select the 32 or 64 bit installer. Install Visual Studio Code on Windows (not in your WSL file system). 25 | 26 | * When prompted to **Select Additional Tasks** during installation, be sure to check the **Add to PATH** option so you can easily open a folder in WSL using the code command. 27 | 28 | * Install the [Remote Development extension pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack). This extension pack includes the WSL extension, in addition to the Remote - SSH, and Dev Containers extensions, enabling you to open any folder in a container, on a remote machine, or in WSL. 29 | 30 | > [!IMPORTANT] 31 | > In order to install the WSL extension, you will need the [1.35 May release](https://code.visualstudio.com/updates/v1_35) version or later of VS Code. We do not recommend using WSL in VS Code without the WSL extension as you will lose support for auto-complete, debugging, linting, etc. Fun fact: this WSL extension is installed in $HOME/.vscode/extensions (enter the command `ls $HOME\.vscode\extensions\` in PowerShell). 32 | 33 | ## Update your Linux distribution 34 | 35 | Some WSL Linux distributions are lacking libraries that are required by the VS Code server to start up. You can add additional libraries into your Linux distribution by using its package manager. 36 | 37 | For example, to update Debian or Ubuntu, use: 38 | 39 | ```bash 40 | sudo apt-get update 41 | ``` 42 | 43 | To add wget (to retrieve content from web servers) and ca-certificates (to allow SSL-based applications to check for the authenticity of SSL connections), enter: 44 | 45 | ```bash 46 | sudo apt-get install wget ca-certificates 47 | ``` 48 | 49 | ## Open a WSL project in Visual Studio Code 50 | 51 | ### From the command-line 52 | 53 | To open a project from your WSL distribution, open the distribution's command line and enter: `code .` 54 | 55 | ![Open WSL project with VS Code remote server](../media/wsl-open-vs-code.gif) 56 | 57 | ### From VS Code 58 | 59 | You can also access more VS Code WSL options by using the shortcut: `CTRL+SHIFT+P` in VS Code to bring up the command palette. If you then type `WSL` you will see a list of the options available, allowing you to reopen the folder in a WSL session, specify which distribution you want to open in, and more. 60 | 61 | ![VS Code's command palette](../media/vscode-remote-command-palette.png) 62 | 63 | ## Extensions inside of VS Code WSL 64 | 65 | The WSL extension splits VS Code into a “client-server” architecture, with the client (the user interface) running on your Windows machine and the server (your code, Git, plugins, etc) running "remotely" in your WSL distribution. 66 | 67 | When running the WSL extension, selecting the 'Extensions' tab will display a list of extensions split between your local machine and your WSL distribution. 68 | 69 | Installing a local extension, like a [theme](https://marketplace.visualstudio.com/search?target=VSCode&category=Themes&sortBy=Installs), only needs to be installed once. 70 | 71 | Some extensions, like the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) or anything that handles things like linting or debugging, must be installed separately on each WSL distribution. VS Code will display a warning icon ⚠, along with a green "Install in WSL" button, if you have an extension locally installed that is not installed on your WSL distribution. 72 | 73 | ![VS Code with WSL extensions vs local extensions](../media/vscode-remote-wsl-extensions.png) 74 | 75 | For further information, see the VS Code docs: 76 | 77 | * When VS Code is started in WSL, no shell startup scripts are run. See this [advanced environment setup script article](https://code.visualstudio.com/docs/remote/wsl#_advanced-environment-setup-script) for more info on how to run additional commands or modify the environment. 78 | 79 | * Having problems launching VS Code from your WSL command line? This [troubleshooting guide](https://code.visualstudio.com/docs/remote/troubleshooting#_fixing-problems-with-the-code-command-not-working) includes tips on changing path variables, resolving extension errors about missing dependencies, resolving Git line ending issues, installing a local VSIX on a remote machine, launching a browser window, blocker localhost port, web sockets not working, errors storing extension data, and more. 80 | 81 | ## Install Git (optional) 82 | 83 | If you plan to collaborate with others, or host your project on an open-source site (like GitHub), VS Code supports [version control with Git](https://code.visualstudio.com/docs/editor/versioncontrol#_git-support). The Source Control tab in VS Code tracks all of your changes and has common Git commands (add, commit, push, pull) built right into the UI. 84 | 85 | To install Git, see [set up Git to work with Windows Subsystem for Linux](./wsl-git.md). 86 | 87 | ## Install Windows Terminal (optional) 88 | 89 | The new Windows Terminal enables multiple tabs (quickly switch between Command Prompt, PowerShell, or multiple Linux distributions), custom key bindings (create your own shortcut keys for opening or closing tabs, copy+paste, etc.), emojis ☺, and custom themes (color schemes, font styles and sizes, background image/blur/transparency). Learn more in the [Windows Terminal docs](/windows/terminal). 90 | 91 | 1. Get [Windows Terminal in the Microsoft Store](https://www.microsoft.com/store/apps/9n0dx20hk701): By installing via the store, updates are handled automatically. 92 | 93 | 2. Once installed, open Windows Terminal and select **Settings** to customize your terminal using the `profile.json` file. 94 | 95 | ## Additional Resources 96 | 97 | * [VS Code WSL documentation](https://code.visualstudio.com/docs/remote/wsl) 98 | * [VS Code WSL tutorial](https://code.visualstudio.com/docs/remote/wsl-tutorial) 99 | * [Remote development tips and tricks](https://code.visualstudio.com/docs/remote/troubleshooting) 100 | * [Using Docker with WSL 2 and VS Code](https://code.visualstudio.com/blogs/2020/03/02/docker-in-wsl2) 101 | * [Using C++ and WSL in VS Code](https://code.visualstudio.com/docs/cpp/config-wsl) 102 | * [Remote R Service for Linux](/visualstudio/rtvs/setting-up-remote-r-service-on-linux) 103 | 104 | A few additional extensions you may want to consider include: 105 | 106 | * [Keymaps from other editors](https://marketplace.visualstudio.com/search?target=VSCode&category=Keymaps&sortBy=Downloads): These extensions can help your environment feel right at home if you're transitioning from another text editor (like Atom, Sublime, Vim, eMacs, Notepad++, etc). 107 | * [Settings Sync](https://marketplace.visualstudio.com/items?itemName=Shan.code-settings-sync): Enables you to synchronize your VS Code settings across different installations using GitHub. If you work on different machines, this helps keep your environment consistent across them. 108 | -------------------------------------------------------------------------------- /WSL/use-custom-distro.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Import any Linux distribution to use with WSL 3 | description: Learn how to import any Linux distribution to use with the Windows Subsystem for Linux. 4 | keywords: BashOnWindows, bash, wsl, windows, windows subsystem, distro, custom 5 | ms.date: 09/27/2021 6 | ms.topic: article 7 | --- 8 | 9 | # Import any Linux distribution to use with WSL 10 | 11 | You can use any Linux distribution inside of the Windows Subsystem for Linux (WSL), even if it is not available in the [Microsoft Store](https://www.microsoft.com/en-us/search/shop/apps?q=linux), by importing it with a tar file. 12 | 13 | This article shows how to import the Linux distribution, [CentOS](https://www.centos.org/), for use with WSL by obtaining its tar file using a Docker container. This process can be applied to import any Linux distribution. 14 | 15 | ## Obtain a tar file for the distribution 16 | 17 | First you'll need to obtain a tar file that contains all the Linux binaries for the distribution. 18 | 19 | You can obtain a tar file in a variety of ways, two of which include: 20 | 21 | - Download a provided tar file. You can find an example for Alpine in the "Mini Root Filesystem" section of the [Alpine Linux downloads](https://alpinelinux.org/downloads/) site. 22 | - Find a Linux distribution container and export an instance as a tar file. The example below will show this process using the [CentOS container](https://hub.docker.com/_/centos). 23 | 24 | ### Obtaining a tar file for CentOS example 25 | 26 | In this example, we'll use Docker inside of a WSL distribution to obtain the tar file for CentOS. 27 | 28 | #### Prerequisites 29 | 30 | - You must have [WSL enabled with a Linux distribution installed running WSL 2](./install-manual.md). 31 | - You must have [Docker Desktop for Windows installed with the WSL 2 engine enabled and integration checked](./tutorials/wsl-containers.md#install-docker-desktop) See the [Docker Desktop license agreement](https://docs.docker.com/subscription/#docker-desktop-license-agreement) for updates on the terms of use. 32 | 33 | #### Export the tar from a container 34 | 35 | 1. Open the command line (Bash) for a Linux distribution that you've already installed from the Microsoft Store (Ubuntu in this example). 36 | 37 | 2. Ensure you have Docker Desktop running (Or if you have Docker installed in the WSL distro start the service with `sudo service docker start` ) 38 | 39 | 3. Run the CentOS container inside Docker: 40 | 41 | ```bash 42 | docker run -t --name wsl_export centos ls / 43 | ``` 44 | 45 | 4. Export the container ID to a tar file on your mounted c-drive: 46 | 47 | ```bash 48 | docker export wsl_export > /mnt/c/temp/centos.tar 49 | ``` 50 | 51 | 5. Clean up the container 52 | 53 | ```bash 54 | docker rm wsl_export 55 | ``` 56 | 57 | ![Example of running the commands above](./media/run-any-distro-tarfile.png) 58 | 59 | This process exports the CentOS tar file from the Docker container so that we can now import it for use locally with WSL. 60 | 61 | ## Import the tar file into WSL 62 | 63 | Once you have a tar file ready, you can import it using the command: `wsl --import `. 64 | 65 | ### Importing CentOS example 66 | 67 | To import the CentOS distribution tar file into WSL: 68 | 69 | 1. Open PowerShell and ensure that you have a folder created where you'd like the distribution to be stored. 70 | 71 | ```PowerShell 72 | cd C:\temp 73 | mkdir E:\wslDistroStorage\CentOS 74 | ``` 75 | 76 | 2. Use the command `wsl --import ` to import the tar file. 77 | 78 | ```PowerShell 79 | wsl --import CentOS E:\wslDistroStorage\CentOS .\centos.tar 80 | ``` 81 | 82 | 3. Use the command `wsl -l -v` to check which distributions you have installed. 83 | 84 | ![Example of the above commands running in WSL](./media/run-any-distro-import.png) 85 | 86 | 4. Finally, use the command `wsl -d CentOS` to run your newly imported CentOS Linux distribution. 87 | 88 | ## Add WSL specific components like a default user 89 | 90 | By default when using --import, you are always started as the root user. You can set up your own user account, but note that the set up process will vary slightly based on each different Linux distribution. 91 | 92 | To set up user account with the CentOS distribution we just imported, first open PowerShell and boot into CentOS, using the command: 93 | 94 | ```PowerShell 95 | wsl -d CentOS 96 | ``` 97 | 98 | Next, open your CentOS command line. Use this command to install sudo and password setting tools into CentOS, create a user account, and set it as the default user. In this example, the username will be 'caloewen'. 99 | 100 | > [!NOTE] 101 | > You will want to add the username to the sudoers file so that enables the user to use sudo. The command `adduser -G wheel $myUsername` adds the user `myUsername` to the wheel group. Users in the wheel group are automatically granted sudo privileges and can perform tasks requiring elevated permission. 102 | 103 | ```bash 104 | yum update -y && yum install passwd sudo -y 105 | myUsername=caloewen 106 | adduser -G wheel $myUsername 107 | echo -e "[user]\ndefault=$myUsername" >> /etc/wsl.conf 108 | passwd $myUsername 109 | ``` 110 | 111 | You must now quit out of that instance and ensure that all WSL instances are terminated. Start your distribution again to see your new default user by running this command in PowerShell: 112 | 113 | ```PowerShell 114 | wsl --terminate CentOS 115 | wsl -d CentOS 116 | ``` 117 | 118 | You will now see `[caloewen@loewen-dev]$` as the output based on this example. 119 | 120 | ![Example of the code above running in WSL](./media/run-any-distro-customuser.png) 121 | 122 | To learn more about configuring WSL settings, see [Configure settings with .wslconfig and wsl.conf](/windows/wsl/wsl-config#configure-settings-with-wslconfig-and-wslconf). 123 | 124 | ## Use a custom Linux distribution 125 | 126 | You can create your own customized Linux distribution, packaged as a UWP app, that will behave exactly like the WSL distributions available in the Microsoft Store. To learn how, see [Creating a Custom Linux Distribution for WSL](./build-custom-distro.md). 127 | -------------------------------------------------------------------------------- /WSL/wsl-plugins.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: WSL Plugins 3 | description: Learn how Windows applications can use WSL plugins to integrate their workflow inside of WSL 4 | ms.date: 10/14/2023 5 | ms.topic: article 6 | --- 7 | 8 | # WSL Plugins 9 | 10 | Windows applications can now create and interact with Linux processes running inside of the Windows Subsystem for Linux (WSL) with WSL plugins. This article gives an overview of how they work, and how to get started using them. 11 | 12 | ## Understanding Plugin functionality 13 | 14 | WSL plugins provide these core functionalities: 15 | 16 | - Allows applications to specify a Windows executable that starts when the WSL virtual machine is started 17 | - The Windows executable can create Linux processes inside of WSL, and it can communicate directly to them using a virtualized socket 18 | 19 | Using these, Windows applications can build ontop of WSL experiences and provide additional functionality related to the Windows Subsystem for Linux. 20 | 21 | ## Installing a Plugin 22 | 23 | As a WSL plugin creator, you can install your plugin on a machine by setting a registry key to point to your plugin’s DLL file. 24 | 25 | And as a WSL user, any application that you use will automatically install WSL plugins as part of their normal install process. 26 | 27 | ## Creating your own Plugin 28 | 29 | To start a plugin project you will need to build a Win32 dll. The simplest way to get set up with this is to try our WSL plugin sample project. You can do this by cloning the [WSL plugin sample repository](https://github.com/microsoft/wsl-plugin-sample) to a local folder with `git clone` and open it in Visual Studio. 30 | 31 | When you open the project please navigate to the `dllmain.cpp` file (https://github.com/microsoft/wsl-plugin-sample/blob/main/plugin.cpp) and you will see the list of functions available to WSL plugins. 32 | 33 | You can then press the “Build” tab and build your project, which will output a DLL ready you to use, likely under `wsl-plugin-sample\x64\Debug\WSLPluginSample.dll`. 34 | 35 | ### Testing your Plugin 36 | 37 | WSL plugins will only run if they are [digitally signed](/windows-hardware/drivers/install/digital-signatures). To test this you will need to enable test signing on your machine. 38 | 39 | #### Enabling test signing and creating a test certification 40 | 41 | Open an elevated PowerShell Window and [enable test signing](/windows-hardware/drivers/install/the-testsigning-boot-configuration-option#enable-or-disable-use-of-test-signed-code) by running this command: 42 | ```powershell 43 | ## If this command results in "The value is protected by Secure Boot policy and cannot be modified or deleted" 44 | ## Then reboot the PC, go into BIOS settings, and disable Secure Boot. BitLocker may also affect your ability to modify this setting. 45 | Bcdedit.exe -set TESTSIGNING ON 46 | ``` 47 | 48 | Once test signing is enabled (A reboot may required), in an elevated Powershell command prompt that is at the directory of your WSLPluginSample.dll file created above we will create a WSL test certificate: 49 | 50 | ```powershell 51 | # Create the cert 52 | $certname = "WSLPluginTestCert" 53 | $cert = New-SelfSignedCertificate -Subject "CN=$certname" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256 -Type CodeSigningCert 54 | 55 | # Export it to a local path 56 | Export-Certificate -Cert $cert -FilePath ".\$certname.cer" 57 | 58 | # Sign the DLL file 59 | Set-AuthenticodeSignature -FilePath "C:\dev\Path\To\Your\WSLPlugin.dll" -Certificate $cert 60 | ``` 61 | 62 | Last import the certificate to the Trusted Root Certification Authority: 63 | 64 | ```powershell 65 | certutil -addstore "Root" ".\$certname.cer" 66 | ``` 67 | 68 | See the [how to create a self signed certificate](/entra/identity-platform/howto-create-self-signed-certificate) docs page for more info. 69 | 70 | #### Install the plugin 71 | 72 | In the same elevated PowerShell window, run the command below to install the plugin, and be sure to change the path to the plugin DLL to your existing path: 73 | 74 | ```powershell 75 | Reg.exe add HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\Plugins /v demo-plugin /t REG_SZ /d C:\Path\to\plugin.dll /f 76 | ``` 77 | 78 | To use the plugin, restart the wsl service via: 79 | 80 | ```powershell 81 | sc.exe stop wslservice 82 | wsl.exe echo “test” 83 | ``` 84 | 85 | Your plugin should now be loaded. See the [Troubleshooting and additional information](#troubleshooting-and-additional-information) section for more information if the plugin failed to load. 86 | 87 | And then when you are finished, you can run this command to remove the plugin (Please keep in mind you will need to restart the WSL service for it to take effect): 88 | 89 | ```powershell 90 | Reg.exe delete HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss\Plugins /v demo-plugin 91 | ``` 92 | 93 | ## Troubleshooting and additional information 94 | 95 | 96 | Common error codes: 97 | 98 | - Wsl/Service/CreateInstance/CreateVm/Plugin/ERROR_MOD_NOT_FOUND -> The plugin DLL could not be loaded. Check that the plugin registration path is correct 99 | - Wsl/Service/CreateInstance/CreateVm/Plugin/TRUST_E_NOSIGNATURE -> The plugin DLL is not signed, or its signature is not trusted by the computer 100 | - Please [enable test signing](/windows-hardware/drivers/install/the-testsigning-boot-configuration-option#enable-or-disable-use-of-test-signed-code) and see [the signing section above on how to set up a test certificate](#enabling-test-signing-and-creating-a-test-certification). 101 | - Wsl/Service/CreateInstance/CreateVm/Plugin/* -> The plugin DLL returned an error in WSLPLUGINAPI_ENTRYPOINTV1 or OnVmStarted() 102 | - Wsl/Service/CreateInstance/Plugin/* -> The plugin DLL returned an error in OnDistributionStarted() 103 | 104 | ## Plugins Linux user space 105 | 106 | Linux processes created via ExecuteBinary() will run in the root namespace of the WSL2 Virtual Machine. This namespace is not associated to any distribution and has a very minimal Mariner based root file system. 107 | 108 | That file system is a writable tmpfs, meaning that all changes made to it will be dropped when the WSL2 Virtual Machine is shut down. 109 | 110 | You can inspect the content of the root namespace by running `wsl --debug-shell` while WSL is running. 111 | 112 | ### Additional considerations 113 | 114 | - All WSL plugin hooks are synchronous, meaning that WSL will wait for the plugin hooks to be completed before continuing. 115 | - Any error returned by a plugin is considered fatal by WSL (meaning that the user’s distribution will not start) 116 | - The plugin code runs in the same address space as the WSL service. Any crash in a plugin will crash the entire WSL service, potentially causing data loss 117 | -------------------------------------------------------------------------------- /WSL/wsl2-mount-disk.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Get started mounting a Linux disk in WSL 2 3 | description: Learn how to set up a disk mount in WSL 2 and how to access it. 4 | ms.date: 07/17/2023 5 | ms.topic: article 6 | --- 7 | 8 | # Mount a Linux disk in WSL 2 9 | 10 | If you want to access a Linux disk format that isn't supported by Windows, you can use WSL 2 to mount your disk and access its content. This tutorial will cover the steps to identify the disk and partition to attach to WSL2, how to mount them, and how to access them. 11 | 12 | If you are connecting an external drive and do not have success with these mounting instructions, you may want to try the instructions to [Connect USB devices](./connect-usb.md). The `wsl --mount` command does not currently support USB/flash drives/SD card readers, ([learn more about this issue](https://github.com/microsoft/WSL/issues/6011)). 13 | 14 | > [!NOTE] 15 | > Administrator access is required to attach a disk to WSL 2. 16 | > The WSL 2 `mount` command does not support mounting a disk (or partitions that belong to the disk) that is currently in use. `wsl --mount` always attaches the entire disk even if only a partition is requested. You can't mount the Windows installation disk. 17 | 18 | ## Prerequisites 19 | 20 | You will need to be on Windows 11 Build 22000 or later, or be running the Microsoft Store version of WSL. To check your WSL and Windows version, use the command: `wsl.exe --version` 21 | 22 | ## Differences between mounting an external drive with Windows formatting versus Linux formatting 23 | 24 | External drives formatted for Windows typically use the NTFS file system formatting. External drives formatted for Linux typically use the Ext4 file system formatting. 25 | 26 | If you have mounted an NTFS-formatted drive on your Windows file system, you can access that drive from your Linux distribution using WSL by creating a mounted directory (`sudo mkdir /mnt/d`, replacing 'd' with whatever drive letter you'd like to use) and then using the `drvfs` file system interop plugin, with the command: 27 | 28 | ```bash 29 | sudo mount -t drvfs D: /mnt/d 30 | ``` 31 | 32 | [Learn more about mounting scenarios](https://superuser.com/questions/1734353/is-there-a-way-to-mount-an-external-drive-when-it-becomes-available-in-wsl). 33 | 34 | If you have an Ext4-formatted drive, you cannot mount it on your Windows file system. In order to mount an Ext4-formatted drive on your Linux distribution with WSL, you can use the `wsl --mount` command following the instructions below. 35 | 36 | ## Mounting an unpartitioned disk 37 | 38 | If you have a disk that doesn't have any partitions, you can mount it directly using the `wsl --mount` command. First you need to identify the disk. 39 | 40 | 1. **Identify the disk** - To list the available disks in Windows, run: 41 | 42 | ```powershell 43 | GET-CimInstance -query "SELECT * from Win32_DiskDrive" 44 | ``` 45 | 46 | The disks paths are available under the 'DeviceID' columns. Usually under the `\\.\PHYSICALDRIVE*` format. 47 | 48 | 2. **Mount the disk** - Using PowerShell, you can mount the disk using the Disk path discovered above, run: 49 | 50 | ```powershell 51 | wsl --mount 52 | ``` 53 | 54 | ![Mounting a drive in WSL](./media/wslmountsimple.png) 55 | 56 | ## Mounting a partitioned disk 57 | 58 | If you have a disk that you aren't sure what file format it is in, or what partitions it has, you can follow the steps below to mount it. 59 | 60 | 1. **Identify the disk** - To list the available disks in Windows, run: 61 | 62 | ```powershell 63 | GET-CimInstance -query "SELECT * from Win32_DiskDrive" 64 | ``` 65 | 66 | The disks paths are listed after 'DeviceID', usually in the `\\.\PHYSICALDRIVE*` format. 67 | 68 | 2. **List and select the partitions to mount in WSL 2** - Once the disk is identified, run: 69 | 70 | ```powershell 71 | wsl --mount --bare 72 | ``` 73 | 74 | This will make the disk available in WSL 2. (In the case of our example, the `` is `\\.\PHYSICALDRIVE*`. 75 | 76 | 3. Once attached, the partition can be listed by running the following command inside WSL 2: 77 | 78 | ```bash 79 | lsblk 80 | ``` 81 | 82 | This will display the available block devices and their partitions. 83 | 84 | Inside Linux, a block device is identified as `/dev/`. For example, /dev/sdb3, is the partition number 3 of disk `sdb`. 85 | 86 | Example output: 87 | 88 | ```bash 89 | NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT 90 | sdb 8:16 0 1G 0 disk 91 | ├─sdb2 8:18 0 50M 0 part 92 | ├─sdb3 8:19 0 873M 0 part 93 | └─sdb1 8:17 0 100M 0 part 94 | sdc 8:32 0 256G 0 disk / 95 | sda 8:0 0 256G 0 disk 96 | ``` 97 | 98 | ### Identifying the filesystem type 99 | 100 | If you don't know the type of filesystem of a disk or partition, you can use this command: 101 | 102 | ```bash 103 | blkid 104 | ``` 105 | 106 | This will output the detected filesystem type (under the `TYPE=""` format). 107 | 108 | ### Mount the selected partitions 109 | 110 | Once you have identified the partitions you want to mount, run this command on each partition: 111 | 112 | ```powershell 113 | wsl --mount --partition --type 114 | ``` 115 | 116 | > [!NOTE] 117 | > If you wish to mount the entire disk as a single volume (i.e. if the disk isn't partitioned), `--partition` can be omitted. 118 | > 119 | > If omitted, the default filesystem type is "ext4". 120 | 121 | ### Access the disk content 122 | 123 | Once mounted, the disk can be accessed under the path pointed to by the config value: `automount.root`. The default value is `/mnt/wsl`. 124 | 125 | From Windows, the disk can be accessed from File Explorer by navigating to: `\\wsl$\\` (pick any Linux distribution). 126 | 127 | ## Unmount the disk 128 | 129 | If you want to unmount and detach the disk from WSL 2, run: 130 | 131 | ```powershell 132 | wsl --unmount 133 | ``` 134 | 135 | ## Mount a VHD in WSL 136 | 137 | > [!NOTE] 138 | > [WSL from the Microsoft Store](https://devblogs.microsoft.com/commandline/a-preview-of-wsl-in-the-microsoft-store-is-now-available/) introduces a new argument to directly mount a VHD: `wsl --mount --vhd ` 139 | > 140 | 141 | You can also mount virtual hard disk files (VHD) into WSL using `wsl --mount`. To do this, you first need to mount the VHD into Windows using the [`Mount-VHD`](/powershell/module/hyper-v/mount-vhd) command in Windows. Be sure to run this command with administrator privileges. Below is an example where we use this command, and also output the disk path. Be sure to replace `` with your actual VHD path. 142 | 143 | ```powershell 144 | Write-Output "\\.\PhysicalDrive$((Mount-VHD -Path -PassThru | Get-Disk).Number)" 145 | ``` 146 | 147 | You can use the output above to obtain the disk path for this VHD and mount that into WSL following the instructions in the previous section. 148 | 149 | You can also use this technique to mount and interact with the virtual hard disks of other WSL distros, as each WSL 2 distro is stored via a virtual hard disk file called: `ext4.vhdx`. By default the VHDs for WSL 2 distros are stored in this path: `C:\Users\[user]\AppData\Local\Packages\[distro]\LocalState\[distroPackageName]`, please exercise caution accessing these system files, this is a power user workflow. Make sure to run `wsl --shutdown` before interacting with this disk to ensure the disk is not in use. 150 | 151 | ![Mounting WSL VHD](./media/wslmountvhd.png) 152 | 153 | ## Command line reference 154 | 155 | ### Mounting a specific filesystem 156 | 157 | By default, WSL 2 will attempt to mount the device as ext4. To specify another filesystem, run: 158 | 159 | ```powershell 160 | wsl --mount -t 161 | ``` 162 | 163 | For example, to mount a disk as fat, run: 164 | 165 | ``` 166 | wsl --mount -t vfat 167 | ``` 168 | 169 | > [!NOTE] 170 | > To list the available filesystems in WSL2, run: `cat /proc/filesystems`
171 | > When a disk has been mounted via WSL2 (Linux file system), it is no longer available to mount via an ext4 driver on the Windows file system. 172 | 173 | ### Mounting a specific partition 174 | 175 | By default, WSL 2 attempts to mount the entire disk. To mount a specific partition, run: 176 | 177 | ``` 178 | wsl --mount -p 179 | ``` 180 | 181 | This only works if the disk is either MBR (Master Boot Record) or GPT (GUID Partition Table). [Read about partition styles - MBR and GPT](/windows-server/storage/disk-management/initialize-new-disks#about-partition-styles---gpt-and-mbr). 182 | 183 | ### Specifying mount options 184 | 185 | To specify mount options, run: 186 | 187 | ```powershell 188 | wsl --mount -o 189 | ``` 190 | 191 | Example: 192 | 193 | ```powershell 194 | wsl --mount -o "data=ordered" 195 | ``` 196 | 197 | > [!NOTE] 198 | > Only filesystem specific options are supported at this time. Generic options such as `ro, rw, noatime, ...` are not supported. 199 | 200 | ### Attaching the disk without mounting it 201 | 202 | If the disk scheme isn't supported by any of the above options, you can attach the disk to WSL 2 without mounting it by running: 203 | 204 | ```powershell 205 | wsl --mount --bare 206 | ``` 207 | 208 | This will make the block device available inside WSL 2 so it can be mounted manually from there. Use `lsblk` to list the available block devices inside WSL 2. 209 | 210 | ### Specifying the mount name 211 | 212 | > [!NOTE] 213 | > This option is only available with [WSL from the Microsoft Store](https://devblogs.microsoft.com/commandline/a-preview-of-wsl-in-the-microsoft-store-is-now-available/) 214 | 215 | By default the mountpoint name is generated based on the physical disk or VHD name. This can be overridden with `--name`. Example: 216 | 217 | ```powershell 218 | wsl --mount --name myDisk 219 | ``` 220 | 221 | ### Detaching a disk 222 | 223 | To detach a disk from WSL 2, run: 224 | 225 | ```powershell 226 | wsl --unmount [DiskPath] 227 | ``` 228 | 229 | If `Diskpath` is omitted, all attached disks are unmounted and detached. 230 | 231 | > [!NOTE] 232 | > If one disk fails to unmount, WSL 2 can be forced to exit by running `wsl --shutdown`, which will detach the disk. 233 | 234 | ## Limitations 235 | 236 | - At this time, only entire disks can be attached to WSL 2, meaning that it's not possible to attach only a partition. Concretely, this means that it's not possible to use `wsl --mount` to read a partition on the boot device, because that device can't be detached from Windows. 237 | 238 | - Only filesystems that are natively supported in the kernel can be mounted by `wsl --mount`. This means that it's not possible to use installed filesystem drivers (such as ntfs-3g for example) by calling `wsl --mount`. 239 | 240 | - Filesystems not directly supported by the kernel can be mounted via a `--bare` attach and then invoking the relevant FUSE driver. 241 | --------------------------------------------------------------------------------