├── .gitignore ├── ChangeLog.md ├── Create-Release.ps1 ├── LICENSE ├── README.md ├── Wsl.Tests.ps1 ├── Wsl.psd1 ├── Wsl.psm1 └── docs ├── Enter-WslDistribution.md ├── Export-WslDistribution.md ├── Get-WslDistribution.md ├── Get-WslDistributionOnline.md ├── Get-WslVersion.md ├── Import-WslDistribution.md ├── Invoke-WslCommand.md ├── Remove-WslDistribution.md ├── Set-WslDistribution.md ├── Stop-Wsl.md ├── Stop-WslDistribution.md └── Wsl.md /.gitignore: -------------------------------------------------------------------------------- 1 | release 2 | Wsl-help.xml -------------------------------------------------------------------------------- /ChangeLog.md: -------------------------------------------------------------------------------- 1 | # What's new in the WSL Management PowerShell module 2 | 3 | ## Version 2.1 (2023-09-27) 4 | 5 | - Added support for retrieving WSL distribution listing from online sources via 6 | [`Get-WslDistributionOnline`][] cmdlet. 7 | 8 | ## Version 2.0 (2023-09-11) 9 | 10 | - Improvements to the [`Import-WslDistribution`][] and [`Export-WslDistribution`][] cmdlets. 11 | - Support importing and exporting VHD files, including importing a VHD in place. 12 | - [`Export-WslDistribution`][] now returns information about the created files, rather than the 13 | distributions. 14 | - The `-Passthru` parameter has been removed from these cmdlets, and they now always return 15 | values. 16 | - Accept paths with custom PowerShell drives, as long as they use the file system provider. 17 | - The [`Invoke-WslCommand`][] and [`Enter-WslDistribution`][] cmdlets support specifying the working 18 | directory and shell type, and support the system distribution. 19 | - The [`Invoke-WslCommand`][] cmdlet supports specifying a command without quoting it, when using 20 | the `-RawCommand` parameter. 21 | - The [`Invoke-WslCommand`][] cmdlet supports running commands using WSLg. 22 | - Added a [`Get-WslVersion`][] command that returns an object with version information about WSL and 23 | its components. 24 | - The [`Get-WslDistribution`][] cmdlet no longer throws an exception if there are no installed WSL 25 | distributions; instead, it just returns no items. 26 | - Added the `WslDistribution.VhdPath` property for WSL2 distributions. 27 | - The `WslDistribution.FileSystemPath` property uses the `\\wsl.localhost` prefix instead of 28 | `\\wsl$`. 29 | - The module now works if the `WSL_UTF8` environment variable is set. 30 | - Added aliases for several parameters on the cmdlets. 31 | - Various bug fixes. 32 | 33 | ## Version 1.0 (2019-10-23) 34 | 35 | - This is the first release of the WSL Management PowerShell module. 36 | 37 | [`Enter-WslDistribution`]: docs/Enter-WslDistribution.md 38 | [`Export-WslDistribution`]: docs/Export-WslDistribution.md 39 | [`Get-WslDistribution`]: docs/Get-WslDistribution.md 40 | [`Get-WslDistributionOnline`]: docs/Get-WslDistributionOnline.md 41 | [`Get-WslVersion`]: docs/Get-WslVersion.md 42 | [`Import-WslDistribution`]: docs/Import-WslDistribution.md 43 | [`Invoke-WslCommand`]: docs/Invoke-WslCommand.md 44 | -------------------------------------------------------------------------------- /Create-Release.ps1: -------------------------------------------------------------------------------- 1 | # Compiles the help, and copies the module files to a folder that can be published using 2 | # Publish-Module. 3 | 4 | #Requires -Modules @{ ModuleName="platyps"; ModuleVersion="0.14.2" } 5 | $outputPath = Join-Path $PSScriptRoot "release" "Wsl" 6 | $docsPath = Join-Path $PSScriptRoot "docs" 7 | New-Item $outputPath -ItemType Directory -Force | Out-Null 8 | Copy-Item "Wsl.psd1","Wsl.psm1" $outputPath 9 | New-ExternalHelp $docsPath -OutputPath $outputPath -Force | Out-Null 10 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 Sven Groot 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # WSL Management for PowerShell [![PowerShell Gallery](https://img.shields.io/powershellgallery/v/Wsl)](https://www.powershellgallery.com/packages/Wsl) 2 | 3 | WSL Management for PowerShell is a PowerShell module that allows you to manage the Windows Subsystem 4 | for Linux (WSL), and its distributions. It provides PowerShell-friendly ways to retrieve information 5 | about distributions, change their settings, import and export them, terminate them, and remove them. 6 | 7 | This module wraps the various functions of `wsl.exe` in PowerShell cmdlets, making it easier to 8 | script each operation. In addition, it provides *tab completion* of distribution names for all the 9 | commands. 10 | 11 | This module has been tested using the inbox WSL version of Windows 10 21h2 (the oldest version still 12 | in mainstream support as of this writing), and using the most recent version of WSL from the 13 | Microsoft Store (version 1.2.5 as of this writing). If you find any problems with other versions 14 | (especially newer store versions), please file an 15 | [issue](https://github.com/SvenGroot/WslManagementPS/issues). 16 | 17 | This module supports both Windows PowerShell and cross-platform 18 | [PowerShell](https://github.com/PowerShell/PowerShell). It can also be run on PowerShell on Linux 19 | inside WSL itself, although not all features are available in this mode. 20 | 21 | ## Why use this module? 22 | 23 | This module offers the following advantages over plain `wsl.exe`: 24 | 25 | - Provides information in PowerShell objects to make it easier to access, filter, and script. 26 | - Provides additional distribution information such as the the installation folder and VHD location. 27 | - Tab completion and wildcard support for distribution names. 28 | - Easily perform operations on multiple distributions (e.g. stop or export/import multiple 29 | distributions with a single command, or run a Linux command on multiple distributions). 30 | 31 | ## Installing the module 32 | 33 | The WSL PowerShell module is available on [PowerShell Gallery](https://www.powershellgallery.com/packages/Wsl), 34 | and can be installed with the `Install-Module` command: 35 | 36 | ```powershell 37 | Install-Module Wsl 38 | ``` 39 | 40 | You can also download the the project from a GitHub release, and copy the files to a folder named 41 | Wsl somewhere in your `$env:PSModulePath`. 42 | 43 | ## Provided commands 44 | 45 | Below, all the commands provided by the module are briefly explained. For more detailed information, 46 | including all parameters and additional examples, follow links for each command or use `Get-Help` 47 | in PowerShell. 48 | 49 | ### Get-WslDistribution 50 | 51 | The [`Get-WslDistribution`][] cmdlet gets information about WSL distributions installed for the 52 | current user. 53 | 54 | This cmdlet wraps the functionality of `wsl.exe --list --verbose`. 55 | 56 | Without parameters, it returns all installed distributions. 57 | 58 | ```powershell 59 | Get-WslDistribution 60 | ``` 61 | 62 | Which could provide the following output, for example: 63 | 64 | ```text 65 | Name State Version Default 66 | ---- ----- ------- ------- 67 | Ubuntu Stopped 2 True 68 | Ubuntu-22.04 Running 1 False 69 | Alpine Running 2 False 70 | Debian Stopped 1 False 71 | ``` 72 | 73 | You can also filter the output using the parameters, by name, version, or state. 74 | 75 | The name supports wildcards; for example, you can retrieve all distributions whose name starts with 76 | "Ubuntu". 77 | 78 | ```powershell 79 | Get-WslDistribution "Ubuntu*" 80 | ``` 81 | 82 | > Note: all cmdlets in this module support wildcards and tab completion on the distribution name. 83 | 84 | To return all running distributions: 85 | 86 | ```powershell 87 | Get-WslDistribution -State Running 88 | ``` 89 | 90 | To return all WSL2 distributions. 91 | 92 | ```powershell 93 | Get-WslDistribution -Version 2 94 | ``` 95 | 96 | You can also get only the default distribution. 97 | 98 | ```powershell 99 | Get-WslDistribution -Default 100 | ``` 101 | 102 | The returned object's type is a custom `WslDistribution` class defined by the module. It has the 103 | following properties: 104 | 105 | Property | Type | Value 106 | -----------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------- 107 | `Name` | System.String | The distribution name. 108 | `State` | WslDistributionState | An enumeration that indicates the current state of the distribution (`Stopped`, `Running`, `Installing`, `Uninstalling`, or `Converting`). 109 | `Version` | System.Int32 | Indicates whether this distribution uses WSL1 or WSL2. 110 | `Default` | System.Boolean | Indicates whether this is the default distribution. 111 | `Guid` | System.Guid | The identifier for the distribution used in the registry and by WSL internally. 112 | `BasePath` | System.String | The full path to the install location of the distribution. 113 | `VhdPath` | System.String | The full path to the distribution's VHD file. This is only set for WSL2 distributions. 114 | `FileSystemPath` | System.String | The UNC path to use to access the distribution's file system, in the form `\\wsl.localhost\`. 115 | 116 | ### Set-WslDistribution 117 | 118 | The [`Set-WslDistribution`][] cmdlet changes the settings of a WSL distribution. You can set a 119 | distribution as default, or convert it between WSL1 and WSL2. 120 | 121 | This cmdlet wraps the functionality of `wsl.exe --set-default` and `wsl.exe --set-version`. 122 | 123 | For example, to set Debian as the default: 124 | 125 | ```powershell 126 | Set-WslDistribution "Debian" -Default 127 | ``` 128 | 129 | To convert all WSL1 distributions to WSL2 130 | 131 | ```powershell 132 | Get-WslDistribution -Version 1 | Set-WslDistribution -Version 2 133 | ``` 134 | 135 | ### Stop-WslDistribution 136 | 137 | The [`Stop-WslDistribution`][] cmdlet terminates a WSL distribution. 138 | 139 | This cmdlet wraps the functionality of `wsl.exe --terminate`. 140 | 141 | For example, to stop all distributions whose name starts with Ubuntu: 142 | 143 | ```powershell 144 | Stop-WslDistribution "Ubuntu*" 145 | ``` 146 | 147 | To stop all running distributions (this avoids showing a warning for non-running distributions): 148 | 149 | ```powershell 150 | Get-WslDistribution -State Running | Stop-WslDistribution 151 | ``` 152 | 153 | ### Remove-WslDistribution 154 | 155 | The [`Remove-WslDistribution`][] cmdlet unregisters a WSL distribution. 156 | 157 | This cmdlet wraps the functionality of `wsl.exe --unregister`. 158 | 159 | :warning: This cmdlet will permanently remove a distribution and all the data stored in its file 160 | system without prompting for confirmation, unless you use `-Confirm`. You can use the `-WhatIf` 161 | parameter to test a command without actually removing anything. 162 | 163 | For example, to remove the distribution named "Ubuntu": 164 | 165 | ```powershell 166 | Remove-WslDistribution "Ubuntu" 167 | ``` 168 | 169 | To remove all WSL1 distributions: 170 | 171 | ```powershell 172 | Get-WslDistribution -Version 1 | Remove-WslDistribution 173 | ``` 174 | 175 | ### Export-WslDistribution 176 | 177 | The [`Export-WslDistribution`][] cmdlet Exports a WSL distribution to a gzipped tarball (`.tar.gz`) 178 | or VHD (`.vhdx`) file. 179 | 180 | You can export multiple distributions in a single command by specifying an existing directory as the 181 | destination. In this case, this cmdlet will automatically create files using the distribution name 182 | with the extension `.tar.gz` or `.vhdx`. 183 | 184 | This cmdlet wraps the functionality of `wsl.exe --export`. 185 | 186 | For example, to export all WS1 distributions to a directory (the directory `D:\backup` has to exist 187 | before running the command): 188 | 189 | ```powershell 190 | Get-WslDistribution -Version 1 | Export-WslDistribution -Destination D:\backup 191 | ``` 192 | 193 | WSL2 distributions can also be exported in VHD format. 194 | 195 | ```powershell 196 | Get-WslDistribution -Version 2 | Export-WslDistribution -Destination D:\backup -Format "Vhd" 197 | ``` 198 | 199 | ### Import-WslDistribution 200 | 201 | The [`Import-WslDistribution`][] cmdlet imports a WSL distribution from a gzipped tarball 202 | (`.tar.gz`) or VHD (`.vhdx`) file. 203 | 204 | By default, this cmdlet derives the distribution name from the input file name, and appends that 205 | name to the destination path. This allows you to import multiple distributions using a single 206 | command. 207 | 208 | This cmdlet wraps the functionality of `wsl.exe --import`. 209 | 210 | For example, to import all `.tar.gz` files from a directory, storing them in subdirectories under 211 | `D:\wsl`: 212 | 213 | ```powershell 214 | Import-WslDistribution D:\backup\*.tar.gz D:\wsl 215 | ``` 216 | 217 | When importing VHD files, you can choose to copy them to a destination, or you can register them 218 | in place: 219 | 220 | ```powershell 221 | Import-WslDistribution D:\backup\*.vhdx -InPlace 222 | ``` 223 | 224 | ### Invoke-WslCommand 225 | 226 | The [`Invoke-WslCommand`][] cmdlet runs a command in a WSL distribution, returning the output as 227 | strings. 228 | 229 | This cmdlet will throw an exception if executing `wsl.exe` failed (e.g. there is no distribution 230 | with the specified name) or if the command returned a non-zero exit code. 231 | 232 | This cmdlet wraps the functionality of `wsl.exe `. 233 | 234 | You can use the cmdlet's parameters to specify the distribution name, Linux user, working directory, 235 | and shell type. 236 | 237 | For example, run a command in all WSL2 distributions as the Linux "root" user: 238 | 239 | ```powershell 240 | Get-WslDistribution -Version 2 | Invoke-WslCommand 'echo $(whoami) in $WSL_DISTRO_NAME' -User root 241 | ``` 242 | 243 | Instead of providing a single quoted command, you can also use the `-RawCommand` parameter to 244 | specify the command without quoting it, similar to how `wsl.exe` itself works: 245 | 246 | ```powershell 247 | Get-WslDistribution -Version 2 | Invoke-WslCommand -RawCommand -User root -- echo $`(whoami`) in `$WSL_DISTRO_NAME 248 | ``` 249 | 250 | Using `--` is not required, but it ensures that nothing after it is interpreted as a parameter to 251 | the cmdlet itself. 252 | 253 | ### Enter-WslDistribution 254 | 255 | The [`Enter-WslDistribution`][] cmdlet starts an interactive session in a WSL distribution. 256 | 257 | This cmdlet will raise an error if executing `wsl.exe` failed (e.g. there is no distribution with 258 | the specified name) or if the session exited with a non-zero exit code. 259 | 260 | This cmdlet wraps the functionality of `wsl.exe` without specifying a command. 261 | 262 | The main advantage of using this cmdlet over plain `wsl.exe` is the availability of tab completion 263 | on the distribution name, or the ability to pipe in a `WslDistribution` retrieved from another 264 | command. 265 | 266 | For example, to enter the Ubuntu distribution as the user root: 267 | 268 | ```powershell 269 | Enter-WslDistribution Ubuntu root 270 | ``` 271 | 272 | To import a distribution and immediately start a session in it: 273 | 274 | ```powershell 275 | Import-WslDistribution D:\backup\Alpine.tar.gz D:\wsl | Enter-WslDistribution 276 | ``` 277 | 278 | ### Get-WslVersion 279 | 280 | The [`Get-WslVersion`][] cmdlet provides version information about the Windows Subsystem for Linux 281 | and its components. It also indicates whether WSL1 or WSL2 is the default. 282 | 283 | For example: 284 | 285 | ```powershell 286 | Get-WslVersion 287 | ``` 288 | 289 | Which outputs: 290 | 291 | ```text 292 | Wsl : 1.2.5.0 293 | Kernel : 5.15.90.1 294 | WslG : 1.0.51 295 | Msrdc : 1.2.3770 296 | Direct3D : 1.608.2 297 | DXCore : 10.0.25131.1002 298 | Windows : 10.0.22621.2215 299 | DefaultDistroVersion : 2 300 | ``` 301 | 302 | The output of this command is a `WslVersionInfo` object, with the properties shown above. All 303 | properties use the type `System.Version`, except for `DefaultDistroVersion` which is a 304 | `System.Int32`. 305 | 306 | If you are using the inbox version of WSL, all properties except for `Windows` and 307 | `DefaultDistroVersion` will be null. 308 | 309 | ### Get-WslDistributionOnline 310 | 311 | The [`Get-WslDistributionOnline`][] cmdlet gets information about WSL distributions available 312 | from online sources. 313 | 314 | This cmdlet wraps the functionality of `wsl.exe --list --online`. 315 | 316 | ```powershell 317 | Get-WslDistributionOnline 318 | ``` 319 | 320 | Which could provide the following output, for example: 321 | 322 | ```text 323 | Name FriendlyName 324 | ---- ------------ 325 | Ubuntu Ubuntu 326 | Debian Debian GNU/Linux 327 | kali-linux Kali Linux Rolling 328 | Ubuntu-18.04 Ubuntu 18.04 LTS 329 | Ubuntu-20.04 Ubuntu 20.04 LTS 330 | Ubuntu-22.04 Ubuntu 22.04 LTS 331 | OracleLinux_7_9 Oracle Linux 7.9 332 | OracleLinux_8_7 Oracle Linux 8.7 333 | OracleLinux_9_1 Oracle Linux 9.1 334 | openSUSE-Leap-15.5 openSUSE Leap 15.5 335 | SUSE-Linux-Enterprise-Server-15-SP4 SUSE Linux Enterprise Server 15 SP4 336 | SUSE-Linux-Enterprise-15-SP5 SUSE Linux Enterprise 15 SP5 337 | openSUSE-Tumbleweed openSUSE Tumbleweed 338 | ``` 339 | 340 | ### Stop-Wsl 341 | 342 | The [`Stop-Wsl`][] cmdlet terminates all WSL distributions, and for WSL2 also shuts down the 343 | lightweight utility VM. 344 | 345 | This cmdlet wraps the functionality of `wsl.exe --shutdown`. 346 | 347 | There is no benefit to using this over `wsl.exe --shutdown`. It is provided purely for the sake of 348 | completionism. 349 | 350 | ## Testing and documentation 351 | 352 | This module uses tests written using [Pester](https://pester.dev/). To execute the tests, clone the 353 | repository and run `Invoke-Pester` in the repository's root directory. 354 | 355 | :warning: The tests assume that the current user does not have any WSL distributions installed prior 356 | to running the tests. If there are pre-existing distributions, you will see a bunch of test failures. 357 | 358 | The tests are written so that pre-existing distributions should not be deleted, unless you have 359 | distributions whose name starts with "wslps_". However, if you are testing changes, bugs in the 360 | module or the tests could cause data loss, so it's strongly recommended to ensure you have no 361 | existing distributions before executing the tests. 362 | 363 | The tests download a tarball for the Alpine distribution, which is used to create distributions for 364 | testing. You can also use a custom tarball by invoking `Wsl.Tests.ps1` directly, using the 365 | `-TestDistroPath` parameter. 366 | 367 | This module uses [PlatyPS](https://github.com/PowerShell/platyPS) to generate an external 368 | documentation file. Markdown sources for the documentation are in the [docs](docs/) directory. 369 | 370 | [`Enter-WslDistribution`]: docs/Enter-WslDistribution.md 371 | [`Export-WslDistribution`]: docs/Export-WslDistribution.md 372 | [`Get-WslDistribution`]: docs/Get-WslDistribution.md 373 | [`Get-WslDistributionOnline`]: docs/Get-WslDistributionOnline.md 374 | [`Get-WslVersion`]: docs/Get-WslVersion.md 375 | [`Import-WslDistribution`]: docs/Import-WslDistribution.md 376 | [`Invoke-WslCommand`]: docs/Invoke-WslCommand.md 377 | [`Remove-WslDistribution`]: docs/Remove-WslDistribution.md 378 | [`Set-WslDistribution`]: docs/Set-WslDistribution.md 379 | [`Stop-Wsl`]: docs/Stop-Wsl.md 380 | [`Stop-WslDistribution`]: docs/Stop-WslDistribution.md 381 | -------------------------------------------------------------------------------- /Wsl.Tests.ps1: -------------------------------------------------------------------------------- 1 | # When adding new functionality, you should: 2 | # - Write tests for the new functionality. 3 | # - Run the tests on both PowerShell Core and Windows PowerShell. 4 | # - Run the tests against the latest WSL store version. 5 | # - Run the tests against the oldest supported WSL inbox version, which should be the oldest Windows 6 | # version still in mainstream support. 7 | # - See https://learn.microsoft.com/lifecycle/products/windows-10-home-and-pro 8 | # 9 | # These tests are not designed to run in PowerShell on Linux inside WSL; only run them directly in 10 | # Windows. 11 | 12 | #Requires -Modules @{ ModuleName="Pester"; ModuleVersion="5.0" } 13 | param( 14 | [Parameter(Mandatory=$false)][string]$TestDistroPath 15 | ) 16 | 17 | BeforeDiscovery { 18 | Import-Module "$PSScriptRoot/Wsl.psd1" -Force 19 | $wslVersion = (Get-WslVersion).Wsl 20 | } 21 | 22 | BeforeAll { 23 | function Test-Distro($Distro, [string]$Name, [string]$Version, [string]$State, [string]$BasePath, [string]$VhdFile = "ext4.vhdx", [Switch]$Default) 24 | { 25 | $Distro | Should -Not -BeNullOrEmpty 26 | $Distro.Name | Should -Be $Name 27 | $Distro.Version | Should -Be $Version 28 | $Distro.State | Should -Be $State 29 | $Distro.Guid | Should -Not -BeNullOrEmpty 30 | if (-not $BasePath) { 31 | $BasePath = "$TestDrive\wsl\$Name" 32 | } 33 | 34 | $Distro.BasePath | Should -Be $BasePath 35 | $Distro.FileSystemPath | Should -Be "\\wsl.localhost\$Name" 36 | $Distro.Default | Should -Be $Default 37 | if ($Distro.Version -eq 2) { 38 | $Distro.VhdPath | Should -Be (Join-Path $BasePath $VhdFile) 39 | 40 | } else { 41 | $Distro.VhdPath | Should -BeNullOrEmpty 42 | } 43 | } 44 | 45 | function Test-DistroEqual($Expected, $Actual) 46 | { 47 | $Expected | Should -Not -BeNullOrEmpty 48 | $Actual | Should -Not -BeNullOrEmpty 49 | $Actual.Name | Should -Be $Expected.Name 50 | $Actual.Version | Should -Be $Expected.Version 51 | $Actual.State | Should -Be $Expected.State 52 | $Actual.Guid | Should -Be $Expected.Guid 53 | $Actual.BasePath | Should -Be $Expected.BasePath 54 | $Actual.FileSystemPath | Should -Be $Expected.FileSystemPath 55 | $Actual.Default | Should -Be $Expected.Default 56 | $Actual.VhdPath | Should -Be $Expected.VhdPath 57 | } 58 | 59 | Write-Warning "These tests should be run on a machine with no existing distributions." 60 | 61 | # This check for arm64 requires cross-platform PowerShell; you can still run the tests with 62 | # Windows PowerShell using the -TestDistroPath parameter. 63 | if ([System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture -eq "Arm64") { 64 | $testDistroUrl = "https://dl-cdn.alpinelinux.org/alpine/v3.18/releases/aarch64/alpine-minirootfs-3.18.3-aarch64.tar.gz" 65 | 66 | } else { 67 | $testDistroUrl = "https://dl-cdn.alpinelinux.org/alpine/v3.18/releases/x86_64/alpine-minirootfs-3.18.3-x86_64.tar.gz" 68 | } 69 | 70 | $testDistroFile = "TestDrive:/wslps_test.tar.gz" 71 | if ($TestDistroPath) { 72 | Copy-Item $TestDistroPath $testDistroFile 73 | 74 | } else { 75 | Invoke-WebRequest $testDistroUrl -OutFile $testDistroFile 76 | } 77 | 78 | New-Item TestDrive:/wsl -ItemType Directory | Out-Null 79 | $originalWslUtf8 = $env:WSL_UTF8 80 | if (Test-Path env:WSL_UTF8) { 81 | Remove-Item env:WSL_UTF8 82 | } 83 | } 84 | 85 | AfterAll { 86 | try { 87 | Remove-WslDistribution "wslps_*" 88 | } catch { 89 | # Don't care about exceptions here. 90 | } 91 | 92 | $env:WSL_UTF8 = $originalWslUtf8 93 | } 94 | 95 | Describe "WslManagementPS" { 96 | It "Can list with no distributions" { 97 | Get-WslDistribution | Should -BeNullOrEmpty 98 | } 99 | 100 | It "Can accept empty collections as pipes" { 101 | # Use the filter string to avoid affecting other distributions if someone ran this test on a 102 | # system that has distributions by mistake. 103 | Get-WslDistribution "wslps_*" | Remove-WslDistribution 104 | Get-WslDistribution "wslps_*" | Stop-WslDistribution 105 | Get-WslDistribution "wslps_*" | Export-WslDistribution -Destination "TestDrive:/wsl" 106 | Get-WslDistribution "wslps_*" | Invoke-WslCommand "echo foo" 107 | Get-WslDistribution "wslps_*" | Set-WslDistribution -Version 2 108 | } 109 | 110 | It "Throws when removing a non-existing distribution" { 111 | { Remove-WslDistribution "wslps_bogus" } | Should -Throw "There is no distribution with the name 'wslps_bogus'." 112 | } 113 | 114 | # A bunch of the below tests depend on this one, so if this one fails, expect more to fail. 115 | It "Can import and export distributions" { 116 | $distro = Import-WslDistribution $testDistroFile -Destination "TestDrive:/wsl" -Version 1 117 | Test-Distro $distro "wslps_test" 1 "Stopped" -Default 118 | Test-DistroEqual $distro (Get-WslDistribution "wslps_test") 119 | 120 | # Already exists 121 | { Import-WslDistribution $testDistroFile -Destination "TestDrive:/" -Version 1 } | Should -Throw 122 | 123 | # Specific name 124 | $distro = Import-WslDistribution $testDistroFile -Name "wslps_test2" -Destination "TestDrive:/wsl" -Version 2 125 | Test-Distro $distro "wslps_test2" 2 "Stopped" 126 | Test-DistroEqual $distro (Get-WslDistribution "wslps_test2") 127 | # Raw destination 128 | New-Item "TestDrive:/wsl/raw" -ItemType Directory 129 | $distro = Import-WslDistribution $testDistroFile -Name "wslps_raw" -Destination "TestDrive:/wsl/raw" -RawDestination -Version 2 130 | Test-Distro $distro "wslps_raw" 2 "Stopped" "$TestDrive\wsl\raw" 131 | Test-DistroEqual $distro (Get-WslDistribution "wslps_raw") 132 | 133 | # Export single distro to file. 134 | $exported = Export-WslDistribution "wslps_test2" "TestDrive:/wslps_exported.tar.gz" 135 | $exported.FullName | Should -Be "$TestDrive\wslps_exported.tar.gz" 136 | Test-Path "TestDrive:/wslps_exported.tar.gz" -PathType Leaf | Should -Be $true 137 | $exported.Length | Should -Not -Be (Get-Item (Get-WslDistribution "wslps_test2").VhdPath).Length 138 | 139 | # Export multiple distros using wildcards 140 | New-Item "TestDrive:/exported" -ItemType Container 141 | Export-WslDistribution "wslps_test*" "TestDrive:/exported" | Out-Null 142 | Test-Path "TestDrive:/exported/wslps_test.tar.gz" -PathType Leaf | Should -Be $true 143 | Test-Path "TestDrive:/exported/wslps_test2.tar.gz" -PathType Leaf | Should -Be $true 144 | (Get-Item "TestDrive:/exported/wslps_test2.tar.gz").Length | Should -Not -Be (Get-Item (Get-WslDistribution "wslps_test2").VhdPath).Length 145 | "TestDrive:/exported/wslps_raw.tar.gz" | Should -Not -Exist 146 | 147 | # Export multiple distros using pipeline 148 | Remove-Item "TestDrive:/exported/*" 149 | Get-WslDistribution -Version 2 | Export-WslDistribution -Destination "TestDrive:/exported" 150 | Test-Path "TestDrive:/exported/wslps_test2.tar.gz" -PathType Leaf | Should -Be $true 151 | Test-Path "TestDrive:/exported/wslps_raw.tar.gz" -PathType Leaf | Should -Be $true 152 | "TestDrive:/exported/wslps_test.tar.gz" | Should -Not -Exist 153 | 154 | # Export non-existant 155 | { Export-WslDistribution "wslps_bogus" "TestDrive:/exported" } | Should -Throw "There is no distribution with the name 'wslps_bogus'." 156 | 157 | Remove-WslDistribution "wslps_test2","wslps_raw" 158 | 159 | # Import multiple distributions using pipeline 160 | $distros = Get-ChildItem "TestDrive:/exported" | Import-WslDistribution -Destination "TestDrive:/wsl" -Version 2 161 | $distros | Should -HaveCount 2 162 | Test-Distro $distros[0] "wslps_raw" 2 "Stopped" 163 | Test-Distro $distros[1] "wslps_test2" 2 "Stopped" 164 | 165 | # Use the default version 166 | $distro = Import-WslDistribution $testDistroFile -Name wslps_default -Destination "TestDrive:/wsl" 167 | $version = Get-WslVersion 168 | Test-Distro $distro "wslps_default" $version.DefaultDistroVersion "Stopped" 169 | { Remove-WslDistribution "wslps_default" } | Should -Not -Throw 170 | } 171 | 172 | It "Can import and export VHDs" -Skip:($wslVersion -lt ([Version]::new(0, 58))) { 173 | try { 174 | Stop-Wsl # Otherwise export may fail due to files in use. 175 | $exported = Export-WslDistribution "wslps_test2" "TestDrive:/exported" -Format "Vhd" 176 | $exported.FullName | Should -Be "$TestDrive\exported\wslps_test2.vhdx" 177 | "TestDrive:/exported/wslps_test2.vhdx" | Should -Exist 178 | $vhdSize = (Get-Item (Get-WslDistribution "wslps_test2").VhdPath).Length 179 | $exported.Length | Should -Be $vhdSize 180 | 181 | # Auto export as VHD based on extension 182 | $exported = Export-WslDistribution "wslps_test2" "TestDrive:/exported/test.vhdx" 183 | $exported.FullName | Should -Be "$TestDrive\exported\test.vhdx" 184 | $exported.Length | Should -Be $vhdSize 185 | 186 | # -Format overrides extension. 187 | $exported = Export-WslDistribution "wslps_test2" "TestDrive:/exported/test2.vhdx" -Format "Tar" 188 | $exported.FullName | Should -Be "$TestDrive\exported\test2.vhdx" 189 | $exported.Length | Should -Not -Be $vhdSize 190 | 191 | # Import VHDs 192 | $distro = Import-WslDistribution "TestDrive:/exported/wslps_test2.vhdx" "TestDrive:/wsl" "wslps_vhd1" 193 | Test-Distro $distro "wslps_vhd1" 2 "Stopped" 194 | $distro = Import-WslDistribution -InPlace "TestDrive:/exported/wslps_test2.vhdx" "wslps_vhd2" 195 | Test-Distro $distro "wslps_vhd2" 2 "Stopped" "$TestDrive\exported" "wslps_test2.vhdx" 196 | 197 | # -Format overrides extension on import 198 | $distro = Import-WslDistribution "TestDrive:/exported/test2.vhdx" "TestDrive:/wsl" "wslps_vhd3" -Format "tar" 199 | Test-Distro $distro "wslps_vhd3" 2 "Stopped" 200 | 201 | } finally { 202 | try { Remove-WslDistribution "wslps_vhd*" } catch {} 203 | } 204 | } 205 | 206 | It "Can list distributions" { 207 | # Invoke a command to start one of the distros. 208 | Invoke-WslCommand "echo foo" "wslps_test2" *> $null 209 | $distros = Get-WslDistribution 210 | $distros | Should -HaveCount 3 211 | Test-Distro ($distros | Where-Object { $_.Name -eq "wslps_test" }) "wslps_test" 1 "Stopped" -Default 212 | Test-Distro ($distros | Where-Object { $_.Name -eq "wslps_raw" }) "wslps_raw" 2 "Stopped" 213 | Test-Distro ($distros | Where-Object { $_.Name -eq "wslps_test2" }) "wslps_test2" 2 "Running" 214 | 215 | $distros = Get-WslDistribution -Default 216 | $distros | Should -HaveCount 1 217 | Test-Distro ($distros | Where-Object { $_.Name -eq "wslps_test" }) "wslps_test" 1 "Stopped" -Default 218 | 219 | $distros = Get-WslDistribution -Version 2 220 | $distros | Should -HaveCount 2 221 | Test-Distro ($distros | Where-Object { $_.Name -eq "wslps_raw" }) "wslps_raw" 2 "Stopped" 222 | Test-Distro ($distros | Where-Object { $_.Name -eq "wslps_test2" }) "wslps_test2" 2 "Running" 223 | 224 | $distros = Get-WslDistribution -State Running 225 | $distros | Should -HaveCount 1 226 | Test-Distro ($distros | Where-Object { $_.Name -eq "wslps_test2" }) "wslps_test2" 2 "Running" 227 | 228 | $distros = Get-WslDistribution -State Stopped -Version 2 229 | $distros | Should -HaveCount 1 230 | Test-Distro ($distros | Where-Object { $_.Name -eq "wslps_raw" }) "wslps_raw" 2 "Stopped" 231 | } 232 | 233 | It "Can list online distributions" { 234 | # Tests that there are online distributions available 235 | $distrosOnline = Get-WslDistributionOnline 236 | $distrosOnline | Should -Not -BeNullOrEmpty 237 | } 238 | 239 | It "Has no missing Name or FriendlyName values" { 240 | # Tests that there are no null or empty values in either Name or FriendlyName 241 | Get-WslDistributionOnline | ForEach-Object { 242 | $_.Name | Should -Not -BeNullOrEmpty 243 | $_.FriendlyName | Should -Not -BeNullOrEmpty 244 | } 245 | } 246 | 247 | It "Supports WSL_UTF8" -Skip:($wslVersion -lt ([Version]::new(0, 64))) { 248 | $env:WSL_UTF8 = "1" 249 | try { 250 | $distros = Get-WslDistribution 251 | $distros | Should -HaveCount 3 252 | Test-Distro ($distros | Where-Object { $_.Name -eq "wslps_test" }) "wslps_test" 1 "Stopped" -Default 253 | Test-Distro ($distros | Where-Object { $_.Name -eq "wslps_raw" }) "wslps_raw" 2 "Stopped" 254 | Test-Distro ($distros | Where-Object { $_.Name -eq "wslps_test2" }) "wslps_test2" 2 "Running" 255 | 256 | } finally { 257 | Remove-Item env:WSL_UTF8 258 | } 259 | } 260 | 261 | It "Can stop distributions" { 262 | # Invoke a command to start the distros. 263 | Invoke-WslCommand "echo foo" "wslps_*" *> $null 264 | 265 | (Get-WslDistribution "wslps_test").State | Should -Be "Running" 266 | (Get-WslDistribution "wslps_test2").State | Should -Be "Running" 267 | (Get-WslDistribution "wslps_raw").State | Should -Be "Running" 268 | 269 | # Wildcards 270 | Stop-WslDistribution "wslps_test*" 271 | (Get-WslDistribution "wslps_test").State | Should -Be "Stopped" 272 | (Get-WslDistribution "wslps_test2").State | Should -Be "Stopped" 273 | (Get-WslDistribution "wslps_raw").State | Should -Be "Running" 274 | 275 | # Exact name and passthru 276 | $distro = Stop-WslDistribution "wslps_raw" -Passthru 277 | Test-Distro $distro "wslps_raw" 2 "Stopped" 278 | 279 | # Pipeline input 280 | Invoke-WslCommand "echo foo" "wslps_*" *> $null 281 | (Get-WslDistribution "wslps_test").State | Should -Be "Running" 282 | (Get-WslDistribution "wslps_test2").State | Should -Be "Running" 283 | (Get-WslDistribution "wslps_raw").State | Should -Be "Running" 284 | Get-WslDistribution -Version 2 | Stop-WslDistribution 285 | (Get-WslDistribution "wslps_test").State | Should -Be "Running" 286 | (Get-WslDistribution "wslps_test2").State | Should -Be "Stopped" 287 | (Get-WslDistribution "wslps_raw").State | Should -Be "Stopped" 288 | 289 | # Non-existent 290 | { Stop-WslDistribution "wslps_bogus" } | Should -Throw "There is no distribution with the name 'wslps_bogus'." 291 | } 292 | 293 | It "Can run commands" { 294 | # Default distro 295 | # Redirect stderr to avoid printing warnings if the current directory can't be translated. 296 | Invoke-WslCommand "whoami" 2> $null | Should -Be "root" 297 | 298 | $uncPrefix = "wsl.localhost" 299 | 300 | # Specific distro 301 | $output = Invoke-WslCommand "cd; wslpath -w ." "wslps_raw" 2> $null 302 | if ($output -eq "\\wsl$\wslps_raw\root") { 303 | # Older WSL versions use this as the prefix. 304 | $uncPrefix = "wsl$" 305 | 306 | } else { 307 | $output | Should -Be "\\wsl.localhost\wslps_raw\root" 308 | } 309 | 310 | # Wildcards 311 | $output = Invoke-WslCommand "cd; wslpath -w ." "wslps_test*" 2> $null 312 | $output | Should -HaveCount 2 313 | $output | Should -Contain "\\$uncPrefix\wslps_test\root" 314 | $output | Should -Contain "\\$uncPrefix\wslps_test2\root" 315 | 316 | # Pipeline input 317 | $output = Get-WslDistribution -Version 2 | Invoke-WslCommand "cd; wslpath -w ." 2> $null 318 | $output | Should -HaveCount 2 319 | $output | Should -Contain "\\$uncPrefix\wslps_raw\root" 320 | $output | Should -Contain "\\$uncPrefix\wslps_test2\root" 321 | 322 | # Set starting directory 323 | Invoke-WslCommand "pwd" -WorkingDirectory "~" 2> $null | Should -Be "/root" 324 | if ((Get-WslVersion).Wsl -gt [Version]::new(0, 56, 1)) { 325 | Invoke-WslCommand "mkdir ~/foo" 2> $null 326 | Invoke-WslCommand "pwd" -WorkingDirectory "~/foo" 2> $null | Should -Be "/root/foo" 327 | } 328 | 329 | Invoke-WslCommand "pwd" -WorkingDirectory "/etc" 2> $null | Should -Be "/etc" 330 | Invoke-WslCommand "pwd" -WorkingDirectory "C:\Windows" 2> $null | Should -Be "/mnt/c/windows" 331 | Invoke-WslCommand "pwd" -WorkingDirectory "C:\" 2> $null | Should -Be "/mnt/c" 332 | $testPath = Invoke-WslCommand "wslpath '$TestDrive\wsl'" 2> $null 333 | Invoke-WslCommand "pwd" -WorkingDirectory "TestDrive:/wsl" 2> $null | Should -Be $testPath 334 | 335 | # Raw command 336 | Invoke-WslCommand -RawCommand -- echo foo`; whoami | Should -Be "foo","root" 337 | 338 | # Shell type (only tests if the argument is accepted; testing it if had any effect is not 339 | # trivial). 340 | if ((Get-WslVersion).Wsl -gt [Version]::new(0, 61, 4)) { 341 | Invoke-WslCommand "echo foo" -ShellType none 2> $null | Should -Be "foo" 342 | Invoke-WslCommand "echo foo" -ShellType login 2> $null | Should -Be "foo" 343 | Invoke-WslCommand -ShellType Standard -RawCommand -- echo foo 2> $null | Should -Be "foo" 344 | } 345 | 346 | # System distribution 347 | if ((Get-WslVersion).Wsl -gt [Version]::new(0, 47, 1)) { 348 | Invoke-WslCommand "whoami" "wslps_test2" -System 2> $null | Should -Be "wslg" 349 | Invoke-WslCommand -DistributionName "wslps_test2" -System -RawCommand whoami 2> $null | Should -Be "wslg" 350 | } 351 | 352 | # Non-existent 353 | { Invoke-WslCommand "whoami" "wslps_bogus" } | Should -Throw "There is no distribution with the name 'wslps_bogus'." 354 | } 355 | 356 | It "Can set distribution properties" { 357 | # Specific distro 358 | $distro = Set-WslDistribution "wslps_test" -Version 2 -Passthru 359 | Test-Distro $distro "wslps_test" 2 "Stopped" -Default 360 | 361 | # Wildcards 362 | $distros = Set-WslDistribution "wslps_test*" -Version 1 -Passthru 363 | Test-Distro $distros[0] "wslps_test" 1 "Stopped" -Default 364 | Test-Distro $distros[1] "wslps_test2" 1 "Stopped" 365 | 366 | # Pipeline input 367 | Get-WslDistribution -Version 1 | Set-WslDistribution -Version 2 368 | Get-WslDistribution -Version 2 | Should -HaveCount 3 369 | 370 | # Change default 371 | Set-WslDistribution "wslps_test2" -Default 372 | (Get-WslDistribution -Default).Name | Should -Be "wslps_test2" 373 | 374 | # Non-existent 375 | { Set-WslDistribution "wslps_bogus" -Version 2 } | Should -Throw "There is no distribution with the name 'wslps_bogus'." 376 | } 377 | 378 | It "Can return version information" { 379 | $version = Get-WslVersion 380 | if ($version.Wsl) { 381 | $packageVersion = (Get-AppxPackage -Name "MicrosoftCorporationII.WindowsSubsystemforLinux").Version 382 | $version.Wsl | Should -Be $packageVersion 383 | $kernelVersion = Invoke-WslCommand "uname -r" 2> $null 384 | $index = $kernelVersion.IndexOf("-") 385 | if ($index -ge 0) { 386 | $kernelVersion = $kernelVersion.Substring(0, $index) 387 | } 388 | 389 | $kernelVersion = [Version]::Parse($kernelVersion) 390 | $version.Kernel | Should -Be $kernelVersion 391 | $version.WslG | Should -BeGreaterThan ([Version]::new()) 392 | $version.Msrdc | Should -BeGreaterThan ([Version]::new()) 393 | $version.Direct3D | Should -BeGreaterThan ([Version]::new()) 394 | $version.DXCore | Should -BeGreaterThan ([Version]::new()) 395 | 396 | } else { 397 | $version.Wsl | Should -BeNullOrEmpty 398 | $version.Kernel | Should -BeNullOrEmpty 399 | $version.WslG | Should -BeNullOrEmpty 400 | $version.Msrdc | Should -BeNullOrEmpty 401 | $version.Direct3D | Should -BeNullOrEmpty 402 | $version.DXCore | Should -BeNullOrEmpty 403 | } 404 | 405 | # Environment.OSVersion always has 0 as the revision so don't compare it. 406 | $version.Windows.Major | Should -Be ([Environment]::OSVersion.Version.Major) 407 | $version.Windows.Minor | Should -Be ([Environment]::OSVersion.Version.Minor) 408 | $version.Windows.Build | Should -Be ([Environment]::OSVersion.Version.Build) 409 | 410 | $version.DefaultDistroVersion -eq 1 -or $version.DefaultDistroVersion -eq 2 | Should -BeTrue 411 | } 412 | 413 | It "Can stop WSL" { 414 | # Invoke a command to start the distros. 415 | Invoke-WslCommand "echo foo" "wslps_*" *> $null 416 | Stop-WSL 417 | Get-WslDistribution -State "Stopped" | Should -HaveCount 3 418 | # Can't really test if the utility VM was stopped. 419 | } 420 | 421 | It "Can remove distributions" { 422 | # Remove explicit name was tested in import/export test. 423 | 424 | # Wildcards 425 | Remove-WslDistribution "wslps_test*" 426 | $distros = Get-WslDistribution 427 | $distros | Should -HaveCount 1 428 | $distros[0].Name | Should -Be "wslps_raw" 429 | 430 | # Pipeline input 431 | Get-WslDistribution | Remove-WslDistribution 432 | Get-WslDistribution | Should -BeNullOrEmpty 433 | 434 | # Non-existent 435 | { Remove-WslDistribution "wslps_bogus" } | Should -Throw "There is no distribution with the name 'wslps_bogus'." 436 | } 437 | } 438 | -------------------------------------------------------------------------------- /Wsl.psd1: -------------------------------------------------------------------------------- 1 | # Copyright (c) Sven Groot. See LICENSE for details. 2 | # 3 | # Module manifest for module 'Wsl' 4 | # 5 | 6 | @{ 7 | 8 | # Script module or binary module file associated with this manifest. 9 | RootModule = 'Wsl.psm1' 10 | 11 | # Version number of this module. 12 | ModuleVersion = '2.1.0' 13 | 14 | # Supported PSEditions 15 | # CompatiblePSEditions = @() 16 | 17 | # ID used to uniquely identify this module 18 | GUID = '5aebb9a8-dbf6-44d3-8c6c-dc343d4e3f0a' 19 | 20 | # Author of this module 21 | Author = 'Sven Groot' 22 | 23 | # Company or vendor of this module 24 | CompanyName = 'Ookii.org' 25 | 26 | # Copyright statement for this module 27 | Copyright = 'Copyright (c) 2019 Sven Groot.' 28 | 29 | # Description of the functionality provided by this module 30 | Description = 'PowerShell cmdlets to manage Windows Subsystem for Linux distributions.' 31 | 32 | # Minimum version of the PowerShell engine required by this module 33 | PowerShellVersion = '5.1' 34 | 35 | # PowerShell editions that this module is compatible with. 36 | CompatiblePSEditions = @('Desktop', 'Core') 37 | 38 | # Name of the PowerShell host required by this module 39 | # PowerShellHostName = '' 40 | 41 | # Minimum version of the PowerShell host required by this module 42 | # PowerShellHostVersion = '' 43 | 44 | # Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only. 45 | # DotNetFrameworkVersion = '' 46 | 47 | # Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only. 48 | # CLRVersion = '' 49 | 50 | # Processor architecture (None, X86, Amd64) required by this module 51 | # ProcessorArchitecture = '' 52 | 53 | # Modules that must be imported into the global environment prior to importing this module 54 | # RequiredModules = @() 55 | 56 | # Assemblies that must be loaded prior to importing this module 57 | # RequiredAssemblies = @() 58 | 59 | # Script files (.ps1) that are run in the caller's environment prior to importing this module. 60 | # ScriptsToProcess = @() 61 | 62 | # Type files (.ps1xml) to be loaded when importing this module 63 | # TypesToProcess = @() 64 | 65 | # Format files (.ps1xml) to be loaded when importing this module 66 | # FormatsToProcess = @() 67 | 68 | # Modules to import as nested modules of the module specified in RootModule/ModuleToProcess 69 | # NestedModules = @() 70 | 71 | # Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export. 72 | FunctionsToExport = @("Get-WslDistribution", 73 | "Set-WslDistribution", 74 | "Stop-WslDistribution", 75 | "Remove-WslDistribution", 76 | "Import-WslDistribution", 77 | "Export-WslDistribution", 78 | "Invoke-WslCommand", 79 | "Enter-WslDistribution", 80 | "Stop-Wsl", 81 | "Get-WslVersion", 82 | "Get-WslDistributionOnline") 83 | 84 | # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export. 85 | CmdletsToExport = @() 86 | 87 | # Variables to export from this module 88 | VariablesToExport = @() 89 | 90 | # Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export. 91 | AliasesToExport = @() 92 | 93 | # DSC resources to export from this module 94 | # DscResourcesToExport = @() 95 | 96 | # List of all modules packaged with this module 97 | # ModuleList = @() 98 | 99 | # List of all files packaged with this module 100 | FileList = @("Wsl.psd1", "Wsl.psm1", "Wsl-help.xml") 101 | 102 | # Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell. 103 | PrivateData = @{ 104 | 105 | PSData = @{ 106 | 107 | # Tags applied to this module. These help with module discovery in online galleries. 108 | Tags = @("WSL", "Windows", "Subsystem", "Linux", "core", "pscore") 109 | 110 | # A URL to the license for this module. 111 | LicenseUri = 'https://github.com/SvenGroot/WslManagementPS/blob/main/LICENSE' 112 | 113 | # A URL to the main website for this project. 114 | ProjectUri = 'https://github.com/SvenGroot/WslManagementPS' 115 | 116 | # A URL to an icon representing this module. 117 | # IconUri = '' 118 | 119 | # ReleaseNotes of this module 120 | ReleaseNotes = 'See https://www.ookii.org/Link/WslManagementPSVersionHistory' 121 | 122 | } # End of PSData hashtable 123 | 124 | } # End of PrivateData hashtable 125 | 126 | # HelpInfo URI of this module 127 | # HelpInfoURI = '' 128 | 129 | # Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix. 130 | # DefaultCommandPrefix = '' 131 | 132 | } 133 | -------------------------------------------------------------------------------- /Wsl.psm1: -------------------------------------------------------------------------------- 1 | # Copyright (c) Sven Groot. See LICENSE for details. 2 | 3 | # Represents the state of a distribution. 4 | enum WslDistributionState { 5 | Stopped 6 | Running 7 | Installing 8 | Uninstalling 9 | Converting 10 | } 11 | 12 | # Represents the format of a distribution to export or import. 13 | enum WslExportFormat { 14 | Auto 15 | Tar 16 | Vhd 17 | } 18 | 19 | # Represents a WSL distribution. 20 | class WslDistribution 21 | { 22 | WslDistribution() 23 | { 24 | $this | Add-Member -Name FileSystemPath -Type ScriptProperty -Value { 25 | return "\\wsl.localhost\$($this.Name)" 26 | } 27 | 28 | $defaultDisplaySet = "Name","State","Version","Default" 29 | 30 | #Create the default property display set 31 | $defaultDisplayPropertySet = New-Object System.Management.Automation.PSPropertySet("DefaultDisplayPropertySet",[string[]]$defaultDisplaySet) 32 | $PSStandardMembers = [System.Management.Automation.PSMemberInfo[]]@($defaultDisplayPropertySet) 33 | $this | Add-Member MemberSet PSStandardMembers $PSStandardMembers 34 | } 35 | 36 | [string] ToString() 37 | { 38 | return $this.Name 39 | } 40 | 41 | [string]$Name 42 | [WslDistributionState]$State 43 | [int]$Version 44 | [bool]$Default 45 | [Guid]$Guid 46 | [string]$BasePath 47 | [string]$VhdPath 48 | } 49 | 50 | # Provides the versions of various WSL components. 51 | class WslVersionInfo { 52 | [Version]$Wsl 53 | [Version]$Kernel 54 | [Version]$WslG 55 | [Version]$Msrdc 56 | [Version]$Direct3D 57 | [Version]$DXCore 58 | [Version]$Windows 59 | [int]$DefaultDistroVersion 60 | } 61 | 62 | # Provides the details of online distributions 63 | class WslDistributionOnline { 64 | [string]$Name 65 | [string]$FriendlyName 66 | } 67 | 68 | # $IsWindows can be used on PowerShell 6+ to determine if we're running on Windows or not. 69 | # On Windows PowerShell 5.1, this variable does not exist so we assume we're running on Windows. 70 | # N.B. We don't assign directly to $IsWindows because that causes a PSScriptAnalyzer warning, since 71 | # it's an automatic variable. All checks should use $IsWindowsOS instead. 72 | if ($PSVersionTable.PSVersion.Major -lt 6) { 73 | $IsWindowsOS = $true 74 | 75 | } else { 76 | $IsWindowsOS = $IsWindows 77 | } 78 | 79 | if ($IsWindowsOS) { 80 | $wslPath = "$env:windir\system32\wsl.exe" 81 | $wslgPath = "$env:windir\system32\wslg.exe" 82 | if (-not [System.Environment]::Is64BitProcess) { 83 | # Allow launching WSL from 32 bit powershell 84 | $wslPath = "$env:windir\sysnative\wsl.exe" 85 | $wslgPath = "$env:windir\sysnative\wslg.exe" 86 | } 87 | 88 | } else { 89 | # If running inside WSL, rely on wsl.exe being in the path. 90 | $wslPath = "wsl.exe" 91 | $wslgPath = "wslg.exe" 92 | } 93 | 94 | function Get-UnresolvedProviderPath([string]$Path) 95 | { 96 | if ($IsWindowsOS) { 97 | return $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($Path) 98 | 99 | } else { 100 | # Don't translate on Linux, because absolute Linux paths will never work, and relative ones 101 | # will. 102 | return $Path 103 | } 104 | } 105 | 106 | # Helper that will launch wsl.exe, correctly parsing its output encoding, and throwing an error 107 | # if it fails. 108 | function Invoke-Wsl([string[]]$WslArgs, [Switch]$IgnoreErrors) 109 | { 110 | try { 111 | $encoding = [System.Text.Encoding]::Unicode 112 | if ($IsLinux) { 113 | # If running inside WSL, we can't easily determine the value WSL_UTF8 had in Windows, 114 | # so set it explicitly. It is set to zero to ensure compatibility with older WSL 115 | # versions that don't support this variable. 116 | $originalWslUtf8 = $env:WSL_UTF8 117 | $originalWslEnv = $env:WSLENV 118 | $env:WSL_UTF8 = "0" 119 | $env:WSLENV += ":WSL_UTF8" 120 | 121 | } elseif ($env:WSL_UTF8 -eq "1") { 122 | $encoding = [System.Text.Encoding]::Utf8 123 | } 124 | 125 | $hasError = $false 126 | if ($PSVersionTable.PSVersion.Major -lt 6 -or $PSVersionTable.PSVersion.Major -ge 7) { 127 | try { 128 | $oldOutputEncoding = [System.Console]::OutputEncoding 129 | [System.Console]::OutputEncoding = $encoding 130 | $output = &$wslPath @WslArgs 131 | if ($LASTEXITCODE -ne 0) { 132 | $hasError = $true 133 | } 134 | 135 | } finally { 136 | [System.Console]::OutputEncoding = $oldOutputEncoding 137 | } 138 | 139 | } else { 140 | # Using Console.OutputEncoding is broken on PowerShell 6, so use an alternative method of 141 | # starting wsl.exe. 142 | # See: https://github.com/PowerShell/PowerShell/issues/10789 143 | $startInfo = New-Object System.Diagnostics.ProcessStartInfo $wslPath 144 | $WslArgs | ForEach-Object { $startInfo.ArgumentList.Add($_) } 145 | $startInfo.RedirectStandardOutput = $true 146 | $startInfo.StandardOutputEncoding = $encoding 147 | $process = [System.Diagnostics.Process]::Start($startInfo) 148 | $output = @() 149 | while ($null -ne ($line = $process.StandardOutput.ReadLine())) { 150 | if ($line.Length -gt 0) { 151 | $output += $line 152 | } 153 | } 154 | 155 | $process.WaitForExit() 156 | if ($process.ExitCode -ne 0) { 157 | $hasError = $true 158 | } 159 | } 160 | 161 | } finally { 162 | if ($IsLinux) { 163 | $env:WSL_UTF8 = $originalWslUtf8 164 | $env:WSLENV = $originalWslEnv 165 | } 166 | } 167 | 168 | # $hasError is used so there's no output in case error action is silently continue. 169 | if ($hasError) { 170 | if (-not $IgnoreErrors) { 171 | throw "Wsl.exe failed: $output" 172 | } 173 | 174 | return @() 175 | } 176 | 177 | return $output 178 | } 179 | 180 | # Helper to parse the output of wsl.exe --list. 181 | # Also used by the tab completion function. 182 | function Get-WslDistributionHelper() 183 | { 184 | Invoke-Wsl "--list","--verbose" -IgnoreErrors | Select-Object -Skip 1 | ForEach-Object { 185 | $fields = $_.Split(@(" "), [System.StringSplitOptions]::RemoveEmptyEntries) 186 | $defaultDistro = $false 187 | if ($fields.Count -eq 4) { 188 | $defaultDistro = $true 189 | $fields = $fields | Select-Object -Skip 1 190 | } 191 | 192 | [WslDistribution]@{ 193 | "Name" = $fields[0] 194 | "State" = $fields[1] 195 | "Version" = [int]$fields[2] 196 | "Default" = $defaultDistro 197 | } 198 | } 199 | } 200 | 201 | # Helper to get additional distribution properties from the registry. 202 | function Get-WslDistributionProperties([WslDistribution]$Distribution) 203 | { 204 | $key = Get-ChildItem "hkcu:\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss" | Get-ItemProperty | Where-Object { $_.DistributionName -eq $Distribution.Name } 205 | if ($key) { 206 | $Distribution.Guid = $key.PSChildName 207 | $Distribution.BasePath = $key.BasePath 208 | if ($Distribution.BasePath.StartsWith("\\?\")) { 209 | $Distribution.BasePath = $Distribution.BasePath.Substring(4) 210 | } 211 | 212 | if ($Distribution.Version -eq 2) { 213 | $vhdFile = "ext4.vhdx" 214 | if ($key.VhdFileName) { 215 | $vhdFile = $key.VhdFileName 216 | } 217 | 218 | $Distribution.VhdPath = Join-Path $Distribution.BasePath $vhdFile 219 | } 220 | } 221 | } 222 | 223 | <# 224 | .EXTERNALHELP 225 | Wsl-help.xml 226 | #> 227 | function Get-WslDistribution 228 | { 229 | [CmdletBinding()] 230 | param( 231 | [Parameter(Mandatory=$false, ValueFromPipeline = $true)] 232 | [Alias("DistributionName")] 233 | [ValidateNotNullOrEmpty()] 234 | [SupportsWildcards()] 235 | [string[]]$Name, 236 | [Parameter(Mandatory=$false)] 237 | [Switch]$Default, 238 | [Parameter(Mandatory=$false)] 239 | [WslDistributionState]$State, 240 | [Parameter(Mandatory=$false)] 241 | [int]$Version 242 | ) 243 | 244 | process { 245 | $distributions = Get-WslDistributionHelper 246 | if ($Default) { 247 | $distributions = $distributions | Where-Object { 248 | $_.Default 249 | } 250 | } 251 | 252 | if ($PSBoundParameters.ContainsKey("State")) { 253 | $distributions = $distributions | Where-Object { 254 | $_.State -eq $State 255 | } 256 | } 257 | 258 | if ($PSBoundParameters.ContainsKey("Version")) { 259 | $distributions = $distributions | Where-Object { 260 | $_.Version -eq $Version 261 | } 262 | } 263 | 264 | if ($Name.Length -gt 0) { 265 | $distributions = $distributions | Where-Object { 266 | foreach ($pattern in $Name) { 267 | if ($_.Name -ilike $pattern) { 268 | return $true 269 | } 270 | } 271 | 272 | return $false 273 | } 274 | } 275 | 276 | # The additional registry properties aren't available if running inside WSL. 277 | if ($IsWindowsOS) { 278 | $distributions | ForEach-Object { 279 | Get-WslDistributionProperties $_ 280 | } 281 | } 282 | 283 | return $distributions 284 | } 285 | } 286 | 287 | <# 288 | .EXTERNALHELP 289 | Wsl-help.xml 290 | #> 291 | 292 | # Retrieves listing of distributions available from online sources 293 | function Get-WslDistributionOnline 294 | { 295 | [CmdletBinding()] 296 | param() 297 | 298 | $store = $false 299 | Invoke-Wsl "--list", "--online" -IgnoreErrors | ForEach-Object { 300 | $name, $friendlyName = $_ -split ' ', 2 301 | if ($store) { 302 | $friendlyName = $friendlyName.Trim() 303 | [WslDistributionOnline]@{ 304 | "Name" = $name 305 | "FriendlyName" = $friendlyName 306 | } 307 | 308 | } elseif ($name -ceq "NAME") { 309 | # The "NAME", "FRIENDLY NAME" header is not localized so can be used to find the start 310 | # of the list 311 | $store = $true 312 | } 313 | } 314 | } 315 | 316 | <# 317 | .EXTERNALHELP 318 | Wsl-help.xml 319 | #> 320 | function Stop-WslDistribution 321 | { 322 | [CmdletBinding(SupportsShouldProcess=$true)] 323 | param( 324 | [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = "DistributionName", Position = 0)] 325 | [Alias("DistributionName")] 326 | [ValidateNotNullOrEmpty()] 327 | [SupportsWildCards()] 328 | [string[]]$Name, 329 | [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = "Distribution")] 330 | [WslDistribution[]]$Distribution, 331 | [Parameter(Mandatory = $false)] 332 | [Switch]$Passthru 333 | ) 334 | 335 | process 336 | { 337 | if ($PSCmdlet.ParameterSetName -eq "DistributionName") { 338 | $distros = Get-WslDistribution $Name 339 | if (-not $distros) { 340 | throw "There is no distribution with the name '$Name'." 341 | } 342 | 343 | } else { 344 | $distros = $Distribution 345 | } 346 | 347 | $distros | ForEach-Object { 348 | if ($_.State -ne [WslDistributionState]::Running) { 349 | Write-Warning "Distribution $($_.Name) is not running." 350 | 351 | } elseif ($PSCmdlet.ShouldProcess($_.Name, "Terminate")) { 352 | Invoke-Wsl "--terminate",$_.Name 353 | } 354 | 355 | if ($Passthru) { 356 | # Re-query to get the updated state. 357 | Get-WslDistribution $_.Name 358 | } 359 | } 360 | } 361 | } 362 | 363 | <# 364 | .EXTERNALHELP 365 | Wsl-help.xml 366 | #> 367 | function Set-WslDistribution 368 | { 369 | [CmdletBinding(SupportsShouldProcess=$true)] 370 | param( 371 | [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = "DistributionName", Position = 0)] 372 | [Alias("DistributionName")] 373 | [ValidateNotNullOrEmpty()] 374 | [SupportsWildCards()] 375 | [string[]]$Name, 376 | [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = "Distribution")] 377 | [WslDistribution[]]$Distribution, 378 | [Parameter(Mandatory = $false)] 379 | [int]$Version = 0, 380 | [Parameter(Mandatory = $false)] 381 | [Switch]$Default, 382 | [Parameter(Mandatory = $false)] 383 | [Switch]$Passthru 384 | ) 385 | 386 | process 387 | { 388 | if ($PSCmdlet.ParameterSetName -eq "DistributionName") { 389 | $distros = Get-WslDistribution $Name 390 | if (-not $distros) { 391 | throw "There is no distribution with the name '$Name'." 392 | } 393 | 394 | } else { 395 | $distros = $Distribution 396 | } 397 | 398 | $distros | ForEach-Object { 399 | if ($Version -ne 0) { 400 | if ($_.Version -eq $Version) { 401 | Write-Warning "The distribution '$($_.Name)' is already the requested version." 402 | 403 | } elseif ($PSCmdlet.ShouldProcess($_.Name, "Set Version")) { 404 | # Suppress output since it messes with passthru 405 | Invoke-Wsl "--set-version",$_.Name,$Version | Out-Null 406 | } 407 | } 408 | 409 | if ($Default) { 410 | if ($_.Default) { 411 | Write-Warning "The distribution '$($_.Name)' is already the default." 412 | 413 | } if ($PSCmdlet.ShouldProcess($_.Name, "Set Default")) { 414 | Invoke-Wsl "--set-default",$_.Name | Out-Null 415 | } 416 | } 417 | 418 | # Get updated info for pass-through. 419 | if ($Passthru) { 420 | Get-WslDistribution $_.Name 421 | } 422 | } 423 | } 424 | } 425 | 426 | <# 427 | .EXTERNALHELP 428 | Wsl-help.xml 429 | #> 430 | function Remove-WslDistribution 431 | { 432 | [CmdletBinding(SupportsShouldProcess=$true)] 433 | param( 434 | [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = "DistributionName", Position = 0)] 435 | [Alias("DistributionName")] 436 | [ValidateNotNullOrEmpty()] 437 | [SupportsWildCards()] 438 | [string[]]$Name, 439 | [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = "Distribution")] 440 | [WslDistribution[]]$Distribution 441 | ) 442 | 443 | process 444 | { 445 | if ($PSCmdlet.ParameterSetName -eq "DistributionName") { 446 | $distros = Get-WslDistribution $Name 447 | if ($distros.Length -eq 0) { 448 | throw "There is no distribution with the name '$Name'." 449 | } 450 | 451 | } else { 452 | $distros = $Distribution 453 | } 454 | 455 | $distros | ForEach-Object { 456 | if ($PSCmdlet.ShouldProcess($_.Name, "Unregister")) { 457 | Invoke-Wsl "--unregister",$_.Name | Out-Null 458 | } 459 | } 460 | } 461 | } 462 | 463 | <# 464 | .EXTERNALHELP 465 | Wsl-help.xml 466 | #> 467 | function Export-WslDistribution 468 | { 469 | [CmdletBinding(SupportsShouldProcess=$true)] 470 | param( 471 | [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = "DistributionName", Position = 0)] 472 | [Alias("DistributionName")] 473 | [ValidateNotNullOrEmpty()] 474 | [SupportsWildCards()] 475 | [string[]]$Name, 476 | [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = "Distribution")] 477 | [WslDistribution[]]$Distribution, 478 | [Parameter(Mandatory = $true, Position = 1)] 479 | [string]$Destination, 480 | [Parameter(Mandatory = $false)] 481 | [Alias("fmt")] 482 | [WslExportFormat]$Format = [WslExportFormat]::Auto 483 | ) 484 | 485 | process 486 | { 487 | if ($PSCmdlet.ParameterSetName -eq "DistributionName") { 488 | $distros = Get-WslDistribution $Name 489 | if (-not $distros) { 490 | throw "There is no distribution with the name '$Name'." 491 | } 492 | 493 | } else { 494 | $distros = $Distribution 495 | } 496 | 497 | $distros | ForEach-Object { 498 | $fullPath = $Destination 499 | $vhd = $false 500 | if (Test-Path $Destination -PathType Container) { 501 | if ($Format -eq [WslExportFormat]::Vhd) { 502 | $extension = ".vhdx" 503 | $vhd = $true 504 | 505 | } else { 506 | $extension = ".tar.gz" 507 | } 508 | 509 | $fullPath = Join-Path $Destination "$($_.Name)$extension" 510 | 511 | } else { 512 | if ($Format -eq [WslExportFormat]::Auto) { 513 | # Split-Path -Extension is not available on Windows PowerShell. 514 | $extension = [System.IO.Path]::GetExtension($Destination) 515 | if ($extension -ieq ".vhdx") { 516 | $vhd = $true 517 | } 518 | 519 | } else { 520 | $vhd = ($Format -eq [WslExportFormat]::Vhd) 521 | } 522 | } 523 | 524 | if (Test-Path $fullPath) { 525 | throw "The path '$fullPath' already exists." 526 | } 527 | 528 | $fullPath = Get-UnresolvedProviderPath $fullPath 529 | if ($PSCmdlet.ShouldProcess("Distribution: $($_.Name), Path: $fullPath", "Export")) { 530 | $wslArgs = @("--export", $_.Name, $fullPath) 531 | if ($vhd) { 532 | $wslArgs += "--vhd" 533 | } 534 | 535 | Invoke-Wsl $wslArgs | Out-Null 536 | Get-Item -LiteralPath $fullPath 537 | } 538 | } 539 | } 540 | } 541 | 542 | <# 543 | .EXTERNALHELP 544 | Wsl-help.xml 545 | #> 546 | function Import-WslDistribution 547 | { 548 | [CmdletBinding(SupportsShouldProcess=$true)] 549 | param( 550 | [Parameter(Mandatory = $true, ParameterSetName = "PathInPlace")] 551 | [Parameter(Mandatory = $true, ParameterSetName = "LiteralPathInPlace")] 552 | [Alias("ip")] 553 | [Switch]$InPlace, 554 | [Parameter(Mandatory = $true, Position = 0, ParameterSetName = "Path", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)] 555 | [Parameter(Mandatory = $true, Position = 0, ParameterSetName = "PathInPlace", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)] 556 | [ValidateNotNullOrEmpty()] 557 | [SupportsWildcards()] 558 | [string[]] $Path, 559 | [Parameter(Mandatory = $true, ParameterSetName = "LiteralPath", ValueFromPipelineByPropertyName = $true)] 560 | [Parameter(Mandatory = $true, ParameterSetName = "LiteralPathInPlace", ValueFromPipelineByPropertyName = $true)] 561 | [Alias("PSPath", "LP")] 562 | [ValidateNotNullOrEmpty()] 563 | [string[]] $LiteralPath, 564 | [Parameter(Mandatory = $true, Position = 1, ParameterSetName = "Path")] 565 | [Parameter(Mandatory = $true, Position = 1, ParameterSetName = "LiteralPath")] 566 | [ValidateNotNullOrEmpty()] 567 | [string]$Destination, 568 | [Parameter(Mandatory = $false, Position = 2)] 569 | [Alias("DistributionName")] 570 | [string]$Name, 571 | [Parameter(Mandatory = $false, Position = 3, ParameterSetName = "Path")] 572 | [Parameter(Mandatory = $false, Position = 3, ParameterSetName = "LiteralPath")] 573 | [int]$Version = 0, 574 | [Parameter(Mandatory = $false, ParameterSetName = "Path")] 575 | [Parameter(Mandatory = $false, ParameterSetName = "LiteralPath")] 576 | [Alias("rd")] 577 | [Switch]$RawDestination, 578 | [Parameter(Mandatory = $false, ParameterSetName = "Path")] 579 | [Parameter(Mandatory = $false, ParameterSetName = "LiteralPath")] 580 | [Alias("fmt")] 581 | [WslExportFormat]$Format = [WslExportFormat]::Auto 582 | ) 583 | 584 | process { 585 | if ($Path) { 586 | $files = Get-Item $Path 587 | } else { 588 | $files = Get-Item -LiteralPath $LiteralPath 589 | } 590 | 591 | $files | ForEach-Object { 592 | $distributionName = $Name 593 | if ($distributionName -eq "") { 594 | $distributionName = $_.BaseName 595 | # If the file name is .tar.gz, the base name isn't what we want. 596 | if ($distributionName.EndsWith(".tar", "OrdinalIgnoreCase")) { 597 | $distributionName = $distributionName.Substring(0, $distributionName.Length - 4) 598 | } 599 | } 600 | 601 | if ($Format -eq [WslExportFormat]::Auto) { 602 | $vhd = $_.Extension -ieq ".vhdx" 603 | 604 | } else { 605 | $vhd = $Format -eq [WslExportFormat]::Vhd 606 | } 607 | 608 | if ($InPlace) { 609 | if ($PSCmdlet.ShouldProcess("Path: $($_.FullName) (in place), Name: $distributionName", "Import")) { 610 | Invoke-Wsl @("--import-in-place", $distributionName, $_.FullName) | Out-Null 611 | Get-WslDistribution $DistributionName 612 | } 613 | 614 | } else { 615 | $distributionDestination = $Destination 616 | if (-not $RawDestination) { 617 | $distributionDestination = Join-Path $distributionDestination $distributionName 618 | } 619 | 620 | $distributionDestination = Get-UnresolvedProviderPath $distributionDestination 621 | if ($PSCmdlet.ShouldProcess("Path: $($_.FullName), Destination: $distributionDestination, Name: $distributionName", "Import")) { 622 | $wslArgs = @("--import", $distributionName, $distributionDestination, $_.FullName) 623 | if ($Version -ne 0) { 624 | $wslArgs += @("--version", $Version) 625 | } 626 | 627 | if ($vhd) { 628 | $wslArgs += "--vhd" 629 | } 630 | 631 | Invoke-Wsl $wslArgs | Out-Null 632 | Get-WslDistribution $DistributionName 633 | } 634 | } 635 | } 636 | } 637 | } 638 | 639 | <# 640 | .EXTERNALHELP 641 | Wsl-help.xml 642 | #> 643 | function Invoke-WslCommand 644 | { 645 | [CmdletBinding(SupportsShouldProcess=$true)] 646 | param( 647 | [Parameter(Mandatory = $true, Position = 0, ParameterSetName = "Distribution")] 648 | [Parameter(Mandatory = $true, Position = 0, ParameterSetName = "DistributionName")] 649 | [ValidateNotNullOrEmpty()] 650 | [string]$Command, 651 | [Parameter(Mandatory = $true, ParameterSetName = "DistributionNameRaw")] 652 | [Parameter(Mandatory = $true, ParameterSetName = "DistributionRaw")] 653 | [Switch]$RawCommand, 654 | [Parameter(Mandatory = $false, ValueFromPipeline = $true, ParameterSetName = "DistributionName", Position = 1)] 655 | [Parameter(Mandatory = $false, ValueFromPipeline = $true, ParameterSetName = "DistributionNameRaw")] 656 | [Alias("DistributionName")] 657 | [ValidateNotNullOrEmpty()] 658 | [SupportsWildCards()] 659 | [string[]]$Name, 660 | [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = "Distribution")] 661 | [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = "DistributionRaw")] 662 | [WslDistribution[]]$Distribution, 663 | [Parameter(Mandatory = $false, Position = 2, ParameterSetName = "Distribution")] 664 | [Parameter(Mandatory = $false, Position = 2, ParameterSetName = "DistributionName")] 665 | [Parameter(Mandatory = $false, ParameterSetName = "DistributionRaw")] 666 | [Parameter(Mandatory = $false, ParameterSetName = "DistributionNameRaw")] 667 | [ValidateNotNullOrEmpty()] 668 | [string]$User, 669 | [Parameter(Mandatory = $false)] 670 | [Alias("wd", "cd")] 671 | [ValidateNotNullOrEmpty()] 672 | [string]$WorkingDirectory, 673 | [Parameter(Mandatory = $false)] 674 | [Alias("st")] 675 | [ValidateSet("Standard", "Login", "None")] 676 | [string]$ShellType, 677 | [Parameter(Mandatory = $false)] 678 | [Switch]$System, 679 | [Parameter(Mandatory = $false)] 680 | [Switch]$Graphical, 681 | [Parameter(Mandatory = $true, ValueFromRemainingArguments = $true, ParameterSetName = "DistributionRaw")] 682 | [Parameter(Mandatory = $true, ValueFromRemainingArguments = $true, ParameterSetName = "DistributionNameRaw")] 683 | [ValidateNotNullOrEmpty()] 684 | [string[]]$Remaining 685 | ) 686 | 687 | process { 688 | if ($Distribution) { 689 | $distros = $Distribution 690 | 691 | } else { 692 | if ($Name) { 693 | $distros = Get-WslDistribution $Name 694 | if (-not $distros) { 695 | throw "There is no distribution with the name '$Name'." 696 | } 697 | 698 | } else { 699 | $distros = Get-WslDistribution -Default 700 | if (-not $distros) { 701 | throw "There is no default distribution." 702 | } 703 | } 704 | 705 | } 706 | 707 | $distros | ForEach-Object { 708 | $wslArgs = @("--distribution", $_.Name) 709 | if ($System) { 710 | $wslArgs += "--system" 711 | } 712 | 713 | if ($User) { 714 | $wslArgs += @("--user", $User) 715 | } 716 | 717 | if ($WorkingDirectory) { 718 | if (-not $WorkingDirectory.StartsWith("~") -and -not $WorkingDirectory.StartsWith("/")) { 719 | $WorkingDirectory = Get-UnresolvedProviderPath $WorkingDirectory 720 | } 721 | 722 | $wslArgs += @("--cd", $WorkingDirectory) 723 | } 724 | 725 | if ($ShellType) { 726 | $wslArgs += @("--shell-type", $ShellType.ToLowerInvariant()) 727 | } 728 | 729 | if ($RawCommand) { 730 | $wslArgs += "--" 731 | $wslArgs += $Remaining 732 | 733 | } else { 734 | # Invoke /bin/sh so the whole command can be passed as a single argument. 735 | $wslArgs += @("/bin/sh", "-c", $Command) 736 | } 737 | 738 | if ($PSCmdlet.ShouldProcess($_.Name, "Invoke Command; args: $wslArgs")) { 739 | if ($Graphical) { 740 | &$wslgPath $wslArgs 741 | 742 | } else { 743 | &$wslPath $wslArgs 744 | } 745 | if ($LASTEXITCODE -ne 0) { 746 | # Note: this could be the exit code of wsl.exe, or of the launched command. 747 | throw "Wsl.exe returned exit code $LASTEXITCODE" 748 | } 749 | } 750 | } 751 | } 752 | } 753 | 754 | <# 755 | .EXTERNALHELP 756 | Wsl-help.xml 757 | #> 758 | function Enter-WslDistribution 759 | { 760 | [CmdletBinding(SupportsShouldProcess=$true)] 761 | param( 762 | [Parameter(Mandatory = $false, ValueFromPipeline = $true, ParameterSetName = "DistributionName", Position = 0)] 763 | [Alias("DistributionName")] 764 | [ValidateNotNullOrEmpty()] 765 | [string]$Name, 766 | [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = "Distribution")] 767 | [WslDistribution]$Distribution, 768 | [Parameter(Mandatory = $false, Position = 1)] 769 | [ValidateNotNullOrEmpty()] 770 | [string]$User, 771 | [Parameter(Mandatory = $false)] 772 | [Alias("wd", "cd")] 773 | [ValidateNotNullOrEmpty()] 774 | [string]$WorkingDirectory, 775 | [Parameter(Mandatory = $false)] 776 | [Alias("st")] 777 | [ValidateSet("Standard", "Login")] 778 | [string]$ShellType, 779 | [Parameter(Mandatory = $false)] 780 | [Switch]$System 781 | ) 782 | 783 | process { 784 | if ($PSCmdlet.ParameterSetName -eq "Distribution") { 785 | $Name = $Distribution.Name 786 | } 787 | 788 | $wslArgs = @() 789 | if ($Name) { 790 | $wslArgs = @("--distribution", $Name) 791 | } 792 | 793 | if ($System) { 794 | $wslArgs += "--system" 795 | } 796 | 797 | if ($User) { 798 | $wslArgs = @("--user", $User) 799 | } 800 | 801 | if ($WorkingDirectory) { 802 | if (-not $WorkingDirectory.StartsWith("~") -and -not $WorkingDirectory.StartsWith("/")) { 803 | $WorkingDirectory = Get-UnresolvedProviderPath $WorkingDirectory 804 | } 805 | 806 | $wslArgs += @("--cd", $WorkingDirectory) 807 | } 808 | 809 | if ($ShellType) { 810 | $wslArgs += @("--shell-type", $ShellType.ToLowerInvariant()) 811 | } 812 | 813 | if ($PSCmdlet.ShouldProcess($Name, "Enter WSL; args: $wslArgs")) { 814 | &$wslPath $wslArgs 815 | if ($LASTEXITCODE -ne 0) { 816 | # Note: this could be the exit code of wsl.exe, or of the shell. 817 | throw "Wsl.exe returned exit code $LASTEXITCODE" 818 | } 819 | } 820 | } 821 | } 822 | 823 | <# 824 | .EXTERNALHELP 825 | Wsl-help.xml 826 | #> 827 | function Stop-Wsl 828 | { 829 | [CmdletBinding(SupportsShouldProcess=$true)] 830 | param() 831 | 832 | if ($PSCmdlet.ShouldProcess("Wsl", "Shutdown")) { 833 | Invoke-Wsl "--shutdown" 834 | } 835 | } 836 | 837 | <# 838 | .EXTERNALHELP 839 | Wsl-help.xml 840 | #> 841 | function Get-WslVersion 842 | { 843 | [CmdletBinding()] 844 | param() 845 | 846 | $output = Invoke-Wsl "--version" -IgnoreErrors | ForEach-Object { 847 | $value = $_ 848 | $index = $_.LastIndexOf(':') 849 | if ($index -ge 0) { 850 | $value = $_.Substring($index + 1).Trim() 851 | } 852 | 853 | $index = $value.IndexOf('-') 854 | if ($index -ge 0) { 855 | $value = $value.Substring(0, $index) 856 | } 857 | 858 | [Version]::Parse($value) 859 | } 860 | 861 | $result = [WslVersionInfo]::new() 862 | if ($output) { 863 | # This relies on the order of the items returned, which is very fragile, but unfortunately 864 | # the names are localized so there is no reliable way to determine which items is which. 865 | $result.Wsl = $output[0] 866 | $result.Kernel = $output[1] 867 | $result.WslG = $output[2] 868 | $result.Msrdc = $output[3] 869 | $result.Direct3D = $output[4] 870 | $result.DXCore = $output[5] 871 | $result.Windows = $output[6] 872 | 873 | } elseif ($IsWindowsOS) { 874 | $result.Windows = [Environment]::OSVersion.Version 875 | } 876 | 877 | if ($IsWindowsOS) { 878 | # Build 20150 is when WSL2 became the default if not specified in the registry. 879 | if ([Environment]::OSVersion.Version -lt [Version]::new(10, 0, 20150)) { 880 | $result.DefaultDistroVersion = 1 881 | 882 | } else { 883 | $result.DefaultDistroVersion = 2 884 | } 885 | 886 | if (Test-Path HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss) { 887 | $props = Get-ItemProperty HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss 888 | if ($props.DefaultVersion) { 889 | $result.DefaultDistroVersion = $props.DefaultVersion 890 | } 891 | } 892 | } 893 | 894 | return $result 895 | } 896 | 897 | $tabCompletionScript = { 898 | param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters) 899 | (Get-WslDistributionHelper).Name | Where-Object { $_ -ilike "$wordToComplete*" } | Sort-Object 900 | } 901 | 902 | Register-ArgumentCompleter -CommandName Get-WslDistribution,Stop-WslDistribution,Set-WslDistribution,Remove-WslDistribution,Export-WslDistribution,Enter-WslDistribution -ParameterName Name -ScriptBlock $tabCompletionScript 903 | Register-ArgumentCompleter -CommandName Invoke-WslCommand -ParameterName DistributionName -ScriptBlock $tabCompletionScript 904 | 905 | Export-ModuleMember Get-WslDistribution 906 | Export-ModuleMember Stop-WslDistribution 907 | Export-ModuleMember Set-WslDistribution 908 | Export-ModuleMember Remove-WslDistribution 909 | Export-ModuleMember Export-WslDistribution 910 | Export-ModuleMember Import-WslDistribution 911 | Export-ModuleMember Invoke-WslCommand 912 | Export-ModuleMember Enter-WslDistribution 913 | Export-ModuleMember Stop-Wsl 914 | Export-ModuleMember Get-WslVersion 915 | Export-ModuleMember Get-WslDistributionOnline 916 | -------------------------------------------------------------------------------- /docs/Enter-WslDistribution.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Wsl-help.xml 3 | Module Name: Wsl 4 | online version: https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Enter-WslDistribution.md 5 | schema: 2.0.0 6 | --- 7 | 8 | # Enter-WslDistribution 9 | 10 | ## SYNOPSIS 11 | 12 | Starts an interactive session in a WSL distribution. 13 | 14 | ## SYNTAX 15 | 16 | ### DistributionName 17 | 18 | ``` 19 | Enter-WslDistribution [[-Name] ] [[-User] ] [-WorkingDirectory ] [-ShellType ] 20 | [-System] [-WhatIf] [-Confirm] [] 21 | ``` 22 | 23 | ### Distribution 24 | 25 | ``` 26 | Enter-WslDistribution -Distribution [[-User] ] [-WorkingDirectory ] 27 | [-ShellType ] [-System] [-WhatIf] [-Confirm] [] 28 | ``` 29 | 30 | ## DESCRIPTION 31 | 32 | The `Enter-WslDistribution` cmdlet starts an interactive shell in a WSL distribution. During the 33 | session, all commands that you type run inside the WSL distribution. You can have only one 34 | interactive session at a time. 35 | 36 | The distribution to enter can be specified by name, or piped in from the `Get-WslDistribution` 37 | cmdlet. If no distribution is specified, the default distribution will be used. 38 | 39 | This cmdlet will throw an exception if executing `wsl.exe` failed (e.g. if there is no distribution 40 | with the specified name), or if the session exited with an non-zero exit code. 41 | 42 | This cmdlet wraps the functionality of `wsl.exe` without specifying a command. 43 | 44 | ## EXAMPLES 45 | 46 | ### EXAMPLE 1 47 | 48 | ```powershell 49 | Enter-WslDistribution 50 | ``` 51 | 52 | This example starts a shell in the default distribution. 53 | 54 | ### EXAMPLE 2 55 | 56 | ```powershell 57 | Enter-WslDistribution Ubuntu root -WorkingDirectory "~" 58 | ``` 59 | 60 | This example starts a shell in the distribution named "Ubuntu", using the "root" user. The starting 61 | directory will be the Linux user's home directory. 62 | 63 | ### EXAMPLE 3 64 | 65 | ```powershell 66 | Import-WslDistribution D:\backup\Alpine.tar.gz D:\wsl | Enter-WslDistribution 67 | ``` 68 | 69 | This example imports a WSL distribution, and immediately starts an interactive session in that 70 | distribution. 71 | 72 | ## PARAMETERS 73 | 74 | ### -Distribution 75 | 76 | Specifies the distribution to enter. 77 | 78 | ```yaml 79 | Type: WslDistribution 80 | Parameter Sets: Distribution 81 | Aliases: 82 | 83 | Required: True 84 | Position: Named 85 | Default value: None 86 | Accept pipeline input: True (ByValue) 87 | Accept wildcard characters: False 88 | ``` 89 | 90 | ### -Name 91 | 92 | Specifies the name of a distribution to enter. Unlike with other cmdlets in this module, this 93 | parameter does not accept wildcards. 94 | 95 | ```yaml 96 | Type: String 97 | Parameter Sets: DistributionName 98 | Aliases: DistributionName 99 | 100 | Required: False 101 | Position: 1 102 | Default value: None 103 | Accept pipeline input: True (ByValue) 104 | Accept wildcard characters: False 105 | ``` 106 | 107 | ### -ShellType 108 | 109 | Specifies the shell type to use for the interactive session, either `Standard` or `Login`. 110 | 111 | This parameter requires at least WSL version 0.64.1. 112 | 113 | ```yaml 114 | Type: String 115 | Parameter Sets: (All) 116 | Aliases: st 117 | 118 | Required: False 119 | Position: Named 120 | Default value: None 121 | Accept pipeline input: False 122 | Accept wildcard characters: False 123 | ``` 124 | 125 | ### -System 126 | 127 | Specifies that the interactive session should use the system distribution. 128 | 129 | This parameter requires at least WSL version 0.47.1. 130 | 131 | ```yaml 132 | Type: SwitchParameter 133 | Parameter Sets: (All) 134 | Aliases: 135 | 136 | Required: False 137 | Position: Named 138 | Default value: False 139 | Accept pipeline input: False 140 | Accept wildcard characters: False 141 | ``` 142 | 143 | ### -User 144 | 145 | Specifies the Linux user to run the interactive session as. If omitted, the default user for the 146 | distribution is used. 147 | 148 | ```yaml 149 | Type: String 150 | Parameter Sets: (All) 151 | Aliases: 152 | 153 | Required: False 154 | Position: 2 155 | Default value: None 156 | Accept pipeline input: False 157 | Accept wildcard characters: False 158 | ``` 159 | 160 | ### -WorkingDirectory 161 | 162 | Specifies the working directory to use for the session. Use `~` for the Linux user's home path. If 163 | the path starts with a `/` character, it will be interpreted as an absolute Linux path. Otherwise, 164 | the value must be a Windows path. 165 | 166 | ```yaml 167 | Type: String 168 | Parameter Sets: (All) 169 | Aliases: wd, cd 170 | 171 | Required: False 172 | Position: Named 173 | Default value: None 174 | Accept pipeline input: False 175 | Accept wildcard characters: False 176 | ``` 177 | 178 | ### -Confirm 179 | 180 | Prompts you for confirmation before running the cmdlet. 181 | 182 | ```yaml 183 | Type: SwitchParameter 184 | Parameter Sets: (All) 185 | Aliases: cf 186 | 187 | Required: False 188 | Position: Named 189 | Default value: None 190 | Accept pipeline input: False 191 | Accept wildcard characters: False 192 | ``` 193 | 194 | ### -WhatIf 195 | 196 | Shows what would happen if the cmdlet runs. 197 | The cmdlet is not run. 198 | 199 | ```yaml 200 | Type: SwitchParameter 201 | Parameter Sets: (All) 202 | Aliases: wi 203 | 204 | Required: False 205 | Position: Named 206 | Default value: None 207 | Accept pipeline input: False 208 | Accept wildcard characters: False 209 | ``` 210 | 211 | ### CommonParameters 212 | 213 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). 214 | 215 | ## INPUTS 216 | 217 | ### WslDistribution 218 | 219 | You can pipe an object retrieved by `Get-WslDistribution` to this cmdlet. 220 | 221 | ### System.String 222 | 223 | You can pipe a distribution name to this cmdlet. 224 | 225 | ## OUTPUTS 226 | 227 | ## NOTES 228 | 229 | ## RELATED LINKS 230 | 231 | [Get-WslDistribution](Get-WslDistribution.md) 232 | 233 | [Invoke-WslCommand](Invoke-WslCommand.md) 234 | -------------------------------------------------------------------------------- /docs/Export-WslDistribution.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Wsl-help.xml 3 | Module Name: Wsl 4 | online version: https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Export-WslDistribution.md 5 | schema: 2.0.0 6 | --- 7 | 8 | # Export-WslDistribution 9 | 10 | ## SYNOPSIS 11 | 12 | Exports a WSL distribution to a gzipped tarball or VHD file. 13 | 14 | ## SYNTAX 15 | 16 | ### DistributionName 17 | 18 | ``` 19 | Export-WslDistribution [-Name] [-Destination] [-Format ] [-WhatIf] 20 | [-Confirm] [] 21 | ``` 22 | 23 | ### Distribution 24 | 25 | ``` 26 | Export-WslDistribution -Distribution [-Destination] [-Format ] 27 | [-WhatIf] [-Confirm] [] 28 | ``` 29 | 30 | ## DESCRIPTION 31 | 32 | The `Export-WslDistribution` cmdlet exports a WSL distributions to a gzipped tarball or VHD file. 33 | The distribution to export can be specified by name, or piped in from the `Get-WslDistribution` 34 | cmdlet. 35 | 36 | If the **Destination** parameter is an existing directory, the name of the distribution, with the 37 | extension `.tar.gz` or `.vhdx`, will be used as the file name. This allows you to export multiple 38 | distributions to a directory using a single command. 39 | 40 | The default behavior is to export the distribution as a gzipped tarball, unless the **Destination** 41 | is a file name ending in `.vhdx`. This format can also be manually selected using the **Format** 42 | parameter. 43 | 44 | This cmdlet wraps the functionality of `wsl.exe --export`. 45 | 46 | ## EXAMPLES 47 | 48 | ### EXAMPLE 1 49 | 50 | ```powershell 51 | Export-WslDistribution "Ubuntu" D:\backup.tar.gz 52 | ``` 53 | 54 | ```Output 55 | Directory: D:\ 56 | 57 | Mode LastWriteTime Length Name 58 | ---- ------------- ------ ---- 59 | -a--- 9/8/2023 2:56 PM 156843008000 backup.tar.gz 60 | ``` 61 | 62 | This example exports the distribution named "Ubuntu" to a file named `D:\backup.tar.gz`. 63 | 64 | ### EXAMPLE 2 65 | 66 | ```powershell 67 | Export-WslDistribution "Ubuntu" D:\backup.vhdx 68 | ``` 69 | 70 | ```Output 71 | Directory: D:\ 72 | 73 | Mode LastWriteTime Length Name 74 | ---- ------------- ------ ---- 75 | -a--- 9/8/2023 12:51 PM 171853217792 backup.vhdx 76 | ``` 77 | 78 | This example exports the distribution named "Ubuntu" to a file named `D:\backup.vhdx`, which is a 79 | VHD, not a gzipped tarball. This requires the distribution to use WSL2. 80 | 81 | ### EXAMPLE 3 82 | 83 | ```powershell 84 | New-Item D:\backup -ItemType Directory 85 | Export-WslDistribution "Ubuntu*" D:\backup 86 | ``` 87 | 88 | ```Output 89 | Directory: D:\backup 90 | 91 | Mode LastWriteTime Length Name 92 | ---- ------------- ------ ---- 93 | -a--- 9/8/2023 2:56 PM 156843008000 Ubuntu.tar.gz 94 | -a--- 9/8/2023 2:56 PM 1336043520 Ubuntu-22.04.tar.gz 95 | ``` 96 | 97 | This example exports all distributions whose name starts with Ubuntu to a directory named 98 | `D:\backup`. Separate `.tar.gz` files will be created for each distribution. 99 | 100 | ### EXAMPLE 4 101 | 102 | ```powershell 103 | Get-WslDistribution -Version 2 | Export-WslDistribution -Destination D:\backup -Format "Vhd" 104 | ``` 105 | 106 | ```Output 107 | Directory: D:\backup 108 | 109 | Mode LastWriteTime Length Name 110 | ---- ------------- ------ ---- 111 | -a--- 9/8/2023 12:51 PM 62914560 Alpine.vhdx 112 | -a--- 9/8/2023 12:51 PM 171853217792 Ubuntu.vhdx 113 | ``` 114 | 115 | This example exports all WSL2 distributions to a directory named `D:\backup`, using VHD format. 116 | 117 | ## PARAMETERS 118 | 119 | ### -Destination 120 | 121 | Specifies the destination directory or file name where the exported distribution will be stored. 122 | 123 | If you specify an existing directory as the destination, a file will be created in that directory 124 | using the distribution name and the extension `.tar.gz` or `.vhdx` depending on the value of the 125 | **Format** parameter. 126 | 127 | If you specify a non-existing path, that path will be used verbatim as the file for the exported 128 | distribution. 129 | 130 | ```yaml 131 | Type: String 132 | Parameter Sets: (All) 133 | Aliases: 134 | 135 | Required: True 136 | Position: 2 137 | Default value: None 138 | Accept pipeline input: False 139 | Accept wildcard characters: False 140 | ``` 141 | 142 | ### -Distribution 143 | 144 | Specifies the distribution to be exported. 145 | 146 | ```yaml 147 | Type: WslDistribution[] 148 | Parameter Sets: Distribution 149 | Aliases: 150 | 151 | Required: True 152 | Position: Named 153 | Default value: None 154 | Accept pipeline input: True (ByValue) 155 | Accept wildcard characters: False 156 | ``` 157 | 158 | ### -Format 159 | 160 | Specifies the format of the exported distribution. `Auto`, which is the default, exports as a 161 | gzipped tarball, unless the **Destination** is a file name ending in `.vhdx`, in which case VHD 162 | format is used; `Tar` exports as a gzipped tarball; and `Vhd` exports as a Virtual Hard Disk. 163 | 164 | Exporting as a VHD is only possible for WSL2 distributions. 165 | 166 | Exporting VHDs requires at least WSL version 0.58. 167 | 168 | ```yaml 169 | Type: WslExportFormat 170 | Parameter Sets: (All) 171 | Aliases: fmt 172 | Accepted values: Auto, Tar, Vhd 173 | 174 | Required: False 175 | Position: Named 176 | Default value: None 177 | Accept pipeline input: False 178 | Accept wildcard characters: False 179 | ``` 180 | 181 | ### -Name 182 | 183 | Specifies the name of a distribution to be exported. 184 | 185 | ```yaml 186 | Type: String[] 187 | Parameter Sets: DistributionName 188 | Aliases: DistributionName 189 | 190 | Required: True 191 | Position: 1 192 | Default value: None 193 | Accept pipeline input: True (ByValue) 194 | Accept wildcard characters: True 195 | ``` 196 | 197 | ### -Confirm 198 | 199 | Prompts you for confirmation before running the cmdlet. 200 | 201 | ```yaml 202 | Type: SwitchParameter 203 | Parameter Sets: (All) 204 | Aliases: cf 205 | 206 | Required: False 207 | Position: Named 208 | Default value: None 209 | Accept pipeline input: False 210 | Accept wildcard characters: False 211 | ``` 212 | 213 | ### -WhatIf 214 | 215 | Shows what would happen if the cmdlet runs. 216 | The cmdlet is not run. 217 | 218 | ```yaml 219 | Type: SwitchParameter 220 | Parameter Sets: (All) 221 | Aliases: wi 222 | 223 | Required: False 224 | Position: Named 225 | Default value: None 226 | Accept pipeline input: False 227 | Accept wildcard characters: False 228 | ``` 229 | 230 | ### CommonParameters 231 | 232 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). 233 | 234 | ## INPUTS 235 | 236 | ### WslDistribution 237 | 238 | You can pipe an object retrieved by `Get-WslDistribution` to this cmdlet. 239 | 240 | ### System.String 241 | 242 | You can pipe a distribution name to this cmdlet. 243 | 244 | ## OUTPUTS 245 | 246 | ### System.IO.FileInfo 247 | 248 | The `FileInfo` object contains information about the file containing the exported distribution. 249 | 250 | ## NOTES 251 | 252 | ## RELATED LINKS 253 | 254 | [Get-WslDistribution](Get-WslDistribution.md) 255 | 256 | [Import-WslDistribution](Import-WslDistribution.md) 257 | -------------------------------------------------------------------------------- /docs/Get-WslDistribution.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Wsl-help.xml 3 | Module Name: Wsl 4 | online version: https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Get-WslDistribution.md 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-WslDistribution 9 | 10 | ## SYNOPSIS 11 | 12 | Gets information about WSL distributions installed for the current user. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Get-WslDistribution [[-Name] ] [-Default] [[-State] ] [[-Version] ] 18 | [] 19 | ``` 20 | 21 | ## DESCRIPTION 22 | 23 | The `Get-WslDistribution` cmdlet gets information about all the WSL distributions installed for the 24 | current user. 25 | 26 | You can filter the output using the parameters of this cmdlet. Use the **Name** parameter to only 27 | return distributions with the specified name, supporting wildcards. Use the **Default** parameter to 28 | return only the default distribution. The **State** parameter filters by states such as `Running` or 29 | `Stopped`, and the **Version** parameter selects only WSL1 or WSL2 distributions. 30 | 31 | This cmdlet wraps the functionality of `wsl.exe --list --verbose`. 32 | 33 | ## EXAMPLES 34 | 35 | ### EXAMPLE 1 36 | 37 | ```powershell 38 | Get-WslDistribution 39 | ``` 40 | 41 | ```Output 42 | Name State Version Default 43 | ---- ----- ------- ------- 44 | Ubuntu Stopped 2 True 45 | Ubuntu-22.04 Running 1 False 46 | Alpine Running 2 False 47 | Debian Stopped 1 False 48 | ``` 49 | 50 | This example lists all WSL distributions. 51 | 52 | ### EXAMPLE 2 53 | 54 | ```powershell 55 | Get-WslDistribution -Default 56 | ``` 57 | 58 | ```Output 59 | Name State Version Default 60 | ---- ----- ------- ------- 61 | Ubuntu Stopped 2 True 62 | ``` 63 | 64 | This example retrieves only the default distribution. 65 | 66 | ### EXAMPLE 3 67 | 68 | ```powershell 69 | Get-WslDistribution -Version 2 -State Running 70 | ``` 71 | 72 | ```Output 73 | Name State Version Default 74 | ---- ----- ------- ------- 75 | Alpine Running 2 False 76 | ``` 77 | 78 | This example gets only those distribution which are running, and are using WSL2. 79 | 80 | ### EXAMPLE 4 81 | 82 | ```powershell 83 | Get-WslDistribution "Ubuntu*" | Stop-WslDistribution 84 | ``` 85 | 86 | This example get all distributions whose name starts with `Ubuntu`, and then terminates them. 87 | 88 | ### EXAMPLE 5 89 | 90 | ```powershell 91 | Get-Content "distributions.txt" | Get-WslDistribution 92 | ``` 93 | 94 | ```Output 95 | Name State Version Default 96 | ---- ----- ------- ------- 97 | Ubuntu Stopped 2 True 98 | Debian Stopped 1 False 99 | ``` 100 | 101 | This example pipes the contents of a file, containing the names of distributions, to the 102 | `Get-WslDistribution` cmdlet. Only the distributions that are listed in the file are returned. 103 | 104 | ## PARAMETERS 105 | 106 | ### -Default 107 | 108 | Specifies that only the default distribution should be returned. If combined with other filter 109 | parameters, the default distribution is only returned if it also matches the other filters; 110 | otherwise, nothing is returned. 111 | 112 | ```yaml 113 | Type: SwitchParameter 114 | Parameter Sets: (All) 115 | Aliases: 116 | 117 | Required: False 118 | Position: Named 119 | Default value: False 120 | Accept pipeline input: False 121 | Accept wildcard characters: False 122 | ``` 123 | 124 | ### -Name 125 | 126 | Specifies the name of a distribution to get detailed information about. 127 | 128 | ```yaml 129 | Type: String[] 130 | Parameter Sets: (All) 131 | Aliases: DistributionName 132 | 133 | Required: False 134 | Position: 1 135 | Default value: None 136 | Accept pipeline input: True (ByValue) 137 | Accept wildcard characters: True 138 | ``` 139 | 140 | ### -State 141 | 142 | Specifies the distribution state (`Stopped`, `Running`, `Installing`, `Uninstalling`, or 143 | `Converting`) to filter the results by. Only distributions in the specified state are returned. 144 | 145 | ```yaml 146 | Type: WslDistributionState 147 | Parameter Sets: (All) 148 | Aliases: 149 | Accepted values: Stopped, Running, Installing, Uninstalling, Converting 150 | 151 | Required: False 152 | Position: 2 153 | Default value: None 154 | Accept pipeline input: False 155 | Accept wildcard characters: False 156 | ``` 157 | 158 | ### -Version 159 | 160 | Specifies the WSL distribution version (1 or 2) to filter the results by. Only distributions using 161 | either WSL1 or WSL2 are returned. 162 | 163 | ```yaml 164 | Type: Int32 165 | Parameter Sets: (All) 166 | Aliases: 167 | 168 | Required: False 169 | Position: 3 170 | Default value: 0 171 | Accept pipeline input: False 172 | Accept wildcard characters: False 173 | ``` 174 | 175 | ### CommonParameters 176 | 177 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). 178 | 179 | ## INPUTS 180 | 181 | ### System.String 182 | 183 | You can pipe a distribution name to this cmdlet. 184 | 185 | ## OUTPUTS 186 | 187 | ### WslDistribution 188 | 189 | This cmdlet returns objects that represent the distributions on the computer. This object has the 190 | following properties: 191 | 192 | - `Name`: The distribution name. 193 | - `State`: The current state of the distribution (`Stopped`, `Running`, `Installing`, `Uninstalling`, or `Converting`). 194 | - `Version`: Indicates whether this distribution uses WSL1 or WSL2. 195 | - `Default`: A boolean that indicates whether this is the default distribution. 196 | - `Guid`: The identifier for the distribution used in the registry and by WSL internally. 197 | - `BasePath`: The install location of the distribution. 198 | - `FileSystemPath`: The path to use to access the distribution's file system, in the form `\\wsl.localhost\distro`. 199 | - `VhdPath`: For WSL2 distributions, the path to the VHD file containing the distribution's file system. 200 | 201 | The `Guid`, `BasePath`, and `VhdPath` properties will be null if this cmdlet was invoked from 202 | Linux PowerShell inside a WSL distribution. 203 | 204 | ## NOTES 205 | 206 | ## RELATED LINKS 207 | 208 | [Get-WslDistributionOnline](Get-WslDistributionOnline.md) 209 | 210 | [Enter-WslDistribution](Enter-WslDistribution.md) 211 | 212 | [Export-WslDistribution](Export-WslDistribution.md) 213 | 214 | [Import-WslDistribution](Import-WslDistribution.md) 215 | 216 | [Invoke-WslCommand](Invoke-WslCommand.md) 217 | 218 | [Remove-WslDistribution](Remove-WslDistribution.md) 219 | 220 | [Set-WslDistribution](Remove-WslDistribution.md) 221 | 222 | [Stop-WslDistribution](Remove-WslDistribution.md) 223 | -------------------------------------------------------------------------------- /docs/Get-WslDistributionOnline.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Wsl-help.xml 3 | Module Name: Wsl 4 | online version: https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Get-WslDistributionOnline.md 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-WslDistributionOnline 9 | 10 | ## SYNOPSIS 11 | 12 | Gets information about WSL distributions available from online sources. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Get-WslDistributionOnline [] 18 | ``` 19 | 20 | ## DESCRIPTION 21 | 22 | The `Get-WslDistributionOnline` cmdlet gets information about all the WSL distributions available 23 | from online sources. 24 | 25 | This cmdlet wraps the functionality of `wsl.exe --list --online`. 26 | 27 | ## EXAMPLES 28 | 29 | ### EXAMPLE 1 30 | 31 | ```powershell 32 | Get-WslDistributionOnline 33 | ``` 34 | 35 | ```Output 36 | Name FriendlyName 37 | ---- ------------ 38 | Ubuntu Ubuntu 39 | Debian Debian GNU/Linux 40 | kali-linux Kali Linux Rolling 41 | Ubuntu-18.04 Ubuntu 18.04 LTS 42 | Ubuntu-20.04 Ubuntu 20.04 LTS 43 | Ubuntu-22.04 Ubuntu 22.04 LTS 44 | OracleLinux_7_9 Oracle Linux 7.9 45 | OracleLinux_8_7 Oracle Linux 8.7 46 | OracleLinux_9_1 Oracle Linux 9.1 47 | openSUSE-Leap-15.5 openSUSE Leap 15.5 48 | SUSE-Linux-Enterprise-Server-15-SP4 SUSE Linux Enterprise Server 15 SP4 49 | SUSE-Linux-Enterprise-15-SP5 SUSE Linux Enterprise 15 SP5 50 | openSUSE-Tumbleweed openSUSE Tumbleweed 51 | ``` 52 | 53 | This example lists all WSL distributions available from online sources. 54 | 55 | ## PARAMETERS 56 | 57 | ### CommonParameters 58 | 59 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). 60 | 61 | ## INPUTS 62 | 63 | ## OUTPUTS 64 | 65 | ### WslDistributionOnline 66 | 67 | This cmdlet returns objects that represent the distributions available from online sources. This 68 | object has the following properties: 69 | 70 | - `Name`: The distribution name that can be used to install it using `wsl.exe --install` 71 | - `FriendlyName`: The Friendly Name for the distribution. 72 | 73 | ## NOTES 74 | 75 | ## RELATED LINKS 76 | 77 | [Get-WslDistribution](Get-WslDistribution.md) 78 | -------------------------------------------------------------------------------- /docs/Get-WslVersion.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Wsl-help.xml 3 | Module Name: Wsl 4 | online version: https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Get-WslVersion.md 5 | schema: 2.0.0 6 | --- 7 | 8 | # Get-WslVersion 9 | 10 | ## SYNOPSIS 11 | 12 | Gets version information about the Windows Subsystem for Linux and its components. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Get-WslVersion [] 18 | ``` 19 | 20 | ## DESCRIPTION 21 | 22 | The `Get-WslVersion` cmdlet gets the version of the WSL store app, as well as other WSL components 23 | such as the Linux kernel and WSLg. 24 | 25 | The returned information includes the default distribution version, which is not a version number, 26 | but a number that indicates whether WSL1 or WSL2 is used by default for newly registered 27 | distributions. 28 | 29 | If WSL is not installed from the Microsoft Store, and the inbox version of WSL is used, all the 30 | versions will be null, except for the `Windows` version and `DefaultDistroVersion`. 31 | 32 | This cmdlet wraps the functionality of `wsl.exe --version`. 33 | 34 | ## EXAMPLES 35 | 36 | ### EXAMPLE 1 37 | 38 | ```powershell 39 | Get-WslVersion 40 | ``` 41 | 42 | ```Output 43 | Wsl : 1.2.5.0 44 | Kernel : 5.15.90.1 45 | WslG : 1.0.51 46 | Msrdc : 1.2.3770 47 | Direct3D : 1.608.2 48 | DXCore : 10.0.25131.1002 49 | Windows : 10.0.22621.2215 50 | DefaultDistroVersion : 2 51 | ``` 52 | 53 | This example gets information about the installed version of WSL. 54 | 55 | ## PARAMETERS 56 | 57 | ### CommonParameters 58 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). 59 | 60 | ## INPUTS 61 | 62 | ## OUTPUTS 63 | 64 | ### WslVersionInfo 65 | 66 | The cmdlet returns an object whose properties represent the versions of WSL components. It has the 67 | following properties: 68 | 69 | - `Wsl`: The version of the WSL app from the Microsoft Store. 70 | - `Kernel`: The Linux kernel version. 71 | - `WslG`: The version of the WSLg component. 72 | - `Msrdc`: The version of the Microsoft Remote Desktop Client. 73 | - `Direct3D`: The version of the Direct3D component. 74 | - `DXCore`: The version of the DXCore component. 75 | - `Windows`: The Windows operating system version. 76 | - `DefaultDistroVersion`: The version that newly registered distributions will use. `1` for WSL1, and `2` for WSL2. 77 | 78 | ## NOTES 79 | 80 | ## RELATED LINKS 81 | -------------------------------------------------------------------------------- /docs/Import-WslDistribution.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Wsl-help.xml 3 | Module Name: Wsl 4 | online version: https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Import-WslDistribution.md 5 | schema: 2.0.0 6 | --- 7 | 8 | # Import-WslDistribution 9 | 10 | ## SYNOPSIS 11 | 12 | Imports a WSL distribution from a gzipped tarball or VHD file. 13 | 14 | ## SYNTAX 15 | 16 | ### LiteralPathInPlace 17 | ``` 18 | Import-WslDistribution [-InPlace] -LiteralPath [[-Name] ] [-WhatIf] [-Confirm] 19 | [] 20 | ``` 21 | 22 | ### PathInPlace 23 | ``` 24 | Import-WslDistribution [-InPlace] [-Path] [[-Name] ] [-WhatIf] [-Confirm] 25 | [] 26 | ``` 27 | 28 | ### Path 29 | 30 | ``` 31 | Import-WslDistribution [-Path] [-Destination] [[-Name] ] [[-Version] ] 32 | [-RawDestination] [-Format ] [-WhatIf] [-Confirm] [] 33 | ``` 34 | 35 | ### LiteralPath 36 | 37 | ``` 38 | Import-WslDistribution -LiteralPath [-Destination] [[-Name] ] [[-Version] ] 39 | [-RawDestination] [-Format ] [-WhatIf] [-Confirm] [] 40 | ``` 41 | 42 | ## DESCRIPTION 43 | 44 | The `Import-WslDistribution` cmdlet imports a WSL distribution that was previously exported to a 45 | gzipped tarball or VHD file, for example using the `Export-WslDistribution` cmdlet. 46 | 47 | If you do not specify a distribution name, the name is derived from the input file name. For example, 48 | a file named "Ubuntu.tar.gz" would be imported to a distribution named "Ubuntu". 49 | 50 | A directory with the name of the distribution is created as a child of the path specified using the 51 | **Destination** parameter, unless the **RawDestination** parameter is used. This allows multiple 52 | distributions to be imported using a single command. 53 | 54 | This cmdlet can be used to import distributions to a new location, or with VHD files it can also 55 | register them using the VHD file in the supplied location using the **InPlace** parameter. 56 | 57 | This cmdlet wraps the functionality of `wsl.exe --import`. 58 | 59 | ## EXAMPLES 60 | 61 | ### EXAMPLE 1 62 | 63 | ```powershell 64 | Import-WslDistribution D:\backup.tar.gz D:\wsl "Ubuntu" 65 | ``` 66 | 67 | ```Output 68 | Name State Version Default 69 | ---- ----- ------- ------- 70 | Ubuntu Stopped 2 False 71 | ``` 72 | 73 | This example imports the file named `D:\backup.tar.gz` as a distribution named "Ubuntu", whose 74 | filesystem will be stored in the directory `D:\wsl\Ubuntu`. 75 | 76 | ### EXAMPLE 2 77 | 78 | ```powershell 79 | Import-WslDistribution D:\backup.tar.gz D:\wsl\mydistro "Ubuntu" -RawDestination 80 | ``` 81 | 82 | ```Output 83 | Name State Version Default 84 | ---- ----- ------- ------- 85 | Ubuntu Stopped 2 False 86 | ``` 87 | 88 | This example imports the file named `D:\backup.tar.gz` as a distribution named "Ubuntu", whose file 89 | system will be stored in the directory `D:\wsl\mydistro`. The name of the distribution is not appended 90 | to this path because the **RawDestination** parameter was used. 91 | 92 | ### EXAMPLE 3 93 | 94 | ```powershell 95 | Import-WslDistribution D:\backup\*.tar.gz D:\wsl 96 | ``` 97 | 98 | ```Output 99 | Name State Version Default 100 | ---- ----- ------- ------- 101 | Alpine Stopped 2 False 102 | Debian Stopped 2 False 103 | Ubuntu Stopped 2 False 104 | ``` 105 | 106 | This example imports all `.tar.gz` files from `D:\backup`, using the base name of each file as the name 107 | of the distribution. Each distribution will be stored in a separate subdirectory of `D:\wsl`. 108 | 109 | ### EXAMPLE 4 110 | 111 | ```powershell 112 | Import-WslDistribution D:\backup\*.vhdx D:\wsl 113 | ``` 114 | 115 | ```Output 116 | Name State Version Default 117 | ---- ----- ------- ------- 118 | Alpine Stopped 2 False 119 | Debian Stopped 2 False 120 | Ubuntu Stopped 2 False 121 | ``` 122 | 123 | This example imports all `.vhdx` files from `D:\backup`, using the base name of each file as the name 124 | of the distribution. Each VHD file will be copied to a separate subdirectory of `D:\wsl`. 125 | 126 | ### EXAMPLE 5 127 | 128 | ```powershell 129 | Import-WslDistribution -InPlace D:\wsl\Ubuntu.vhdx | Set-WslDistribution -Default 130 | ``` 131 | 132 | This example imports the file named `D:\wsl\Ubuntu.vhdx` as a distribution named "Ubuntu", using the 133 | file at its present location. It then makes the new distribution the default distribution. 134 | 135 | ### EXAMPLE 6 136 | 137 | ```powershell 138 | Get-Item D:\backup\*.tar.gz -Exclude "Ubuntu*" | Import-WslDistribution -Destination D:\wsl -Version 1 139 | ``` 140 | 141 | ```Output 142 | Name State Version Default 143 | ---- ----- ------- ------- 144 | Alpine Stopped 1 False 145 | Debian Stopped 1 False 146 | ``` 147 | 148 | This example imports all `.tar.gz` files, except those whose names start with Ubuntu, as WSL1 149 | distributions stored in subdirectories of `D:\wsl`. 150 | 151 | ## PARAMETERS 152 | 153 | ### -Destination 154 | 155 | Specifies the destination directory where the file system for the imported distribution will be 156 | stored. 157 | 158 | Unless the **RawDestination** parameter is used, the name of the distribution will be appended to 159 | this path as a subdirectory. 160 | 161 | ```yaml 162 | Type: String 163 | Parameter Sets: Path, LiteralPath 164 | Aliases: 165 | 166 | Required: True 167 | Position: 2 168 | Default value: None 169 | Accept pipeline input: False 170 | Accept wildcard characters: False 171 | ``` 172 | 173 | ### -Format 174 | 175 | Specifies the format of the file to import, which can be either a gzipped tarball or a VHD. `Auto` 176 | determines the format based on the file extension; `Tar` indicates the file is a gzipped tarball; 177 | and `Vhd` indicates the file is a Virtual Hard Disk. 178 | 179 | When using `Auto`, all files are assumed to be gzipped tarballs, unless their name ends in `.vhdx`. 180 | 181 | Importing VHDs requires at least WSL version 0.58. 182 | 183 | ```yaml 184 | Type: WslExportFormat 185 | Parameter Sets: Path, LiteralPath 186 | Aliases: fmt 187 | 188 | Required: False 189 | Position: Named 190 | Default value: None 191 | Accept pipeline input: False 192 | Accept wildcard characters: False 193 | ``` 194 | 195 | ### -InPlace 196 | 197 | Specifies that the new distribution should use the input file in its current location, without 198 | copying it. The input must be a `.vhdx` file when importing in place. 199 | 200 | This parameter requires at least WSL version 0.58. 201 | 202 | ```yaml 203 | Type: SwitchParameter 204 | Parameter Sets: LiteralPathInPlace, PathInPlace 205 | Aliases: ip 206 | 207 | Required: True 208 | Position: Named 209 | Default value: False 210 | Accept pipeline input: False 211 | Accept wildcard characters: False 212 | ``` 213 | 214 | ### -LiteralPath 215 | 216 | Specifies the path to a `.tar.gz` or `.vhdx` file to import. The value of **LiteralPath** is used 217 | exactly as it is typed. No characters are interpreted as wildcards. 218 | 219 | ```yaml 220 | Type: String[] 221 | Parameter Sets: LiteralPathInPlace, LiteralPath 222 | Aliases: PSPath, LP 223 | 224 | Required: True 225 | Position: Named 226 | Default value: None 227 | Accept pipeline input: True (ByPropertyName) 228 | Accept wildcard characters: False 229 | ``` 230 | 231 | ### -Name 232 | 233 | Specifies the name of the imported WSL distribution. 234 | 235 | If you specify an explicit distribution name, you cannot import multiple distributions with a single 236 | command. 237 | 238 | ```yaml 239 | Type: String 240 | Parameter Sets: (All) 241 | Aliases: DistributionName 242 | 243 | Required: False 244 | Position: 3 245 | Default value: None 246 | Accept pipeline input: False 247 | Accept wildcard characters: False 248 | ``` 249 | 250 | ### -Path 251 | 252 | Specifies the path to a `.tar.gz` or `.vhdx` file to import. Wildcard characters are permitted. 253 | 254 | ```yaml 255 | Type: String[] 256 | Parameter Sets: PathInPlace, Path 257 | Aliases: 258 | 259 | Required: True 260 | Position: 1 261 | Default value: None 262 | Accept pipeline input: True (ByPropertyName, ByValue) 263 | Accept wildcard characters: True 264 | ``` 265 | 266 | ### -RawDestination 267 | 268 | Specifies that the **Destination** path should be used as is, without appending the distribution 269 | name to it. 270 | 271 | If **RawDestination** is specified, you cannot import multiple distributions with one command. 272 | 273 | ```yaml 274 | Type: SwitchParameter 275 | Parameter Sets: Path, LiteralPath 276 | Aliases: rd 277 | 278 | Required: False 279 | Position: Named 280 | Default value: False 281 | Accept pipeline input: False 282 | Accept wildcard characters: False 283 | ``` 284 | 285 | ### -Version 286 | 287 | Specifies the distribution version to use for the imported distribution, either 1 or 2. 288 | 289 | If omitted, the currently configured default distribution version is used. 290 | 291 | ```yaml 292 | Type: Int32 293 | Parameter Sets: Path, LiteralPath 294 | Aliases: 295 | 296 | Required: False 297 | Position: 4 298 | Default value: 0 299 | Accept pipeline input: False 300 | Accept wildcard characters: False 301 | ``` 302 | 303 | ### -Confirm 304 | 305 | Prompts you for confirmation before running the cmdlet. 306 | 307 | ```yaml 308 | Type: SwitchParameter 309 | Parameter Sets: (All) 310 | Aliases: cf 311 | 312 | Required: False 313 | Position: Named 314 | Default value: None 315 | Accept pipeline input: False 316 | Accept wildcard characters: False 317 | ``` 318 | 319 | ### -WhatIf 320 | 321 | Shows what would happen if the cmdlet runs. 322 | The cmdlet is not run. 323 | 324 | ```yaml 325 | Type: SwitchParameter 326 | Parameter Sets: (All) 327 | Aliases: wi 328 | 329 | Required: False 330 | Position: Named 331 | Default value: None 332 | Accept pipeline input: False 333 | Accept wildcard characters: False 334 | ``` 335 | 336 | ### CommonParameters 337 | 338 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). 339 | 340 | ## INPUTS 341 | 342 | ### System.String 343 | 344 | You can pipe a string that contains a path to this cmdlet. 345 | 346 | ## OUTPUTS 347 | 348 | ### WslDistribution 349 | 350 | An object representing the imported distribution. See `Get-WslDistribution` for more information. 351 | 352 | ## NOTES 353 | 354 | ## RELATED LINKS 355 | 356 | [Get-WslDistribution](Get-WslDistribution.md) 357 | 358 | [Export-WslDistribution](Export-WslDistribution.md) 359 | -------------------------------------------------------------------------------- /docs/Invoke-WslCommand.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Wsl-help.xml 3 | Module Name: Wsl 4 | online version: https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Invoke-WslCommand.md 5 | schema: 2.0.0 6 | --- 7 | 8 | # Invoke-WslCommand 9 | 10 | ## SYNOPSIS 11 | 12 | Runs a command in a WSL distribution. 13 | 14 | ## SYNTAX 15 | 16 | ### DistributionName 17 | 18 | ``` 19 | Invoke-WslCommand [-Command] [-Name ] [[-User] ] [-WorkingDirectory ] 20 | [-ShellType ] [-System] [-Graphical] [-WhatIf] [-Confirm] [] 21 | ``` 22 | 23 | ### Distribution 24 | 25 | ``` 26 | Invoke-WslCommand [-Command] -Distribution [[-User] ] 27 | [-WorkingDirectory ] [-ShellType ] [-System] [-Graphical] [-WhatIf] [-Confirm] 28 | [] 29 | ``` 30 | 31 | ### DistributionRaw 32 | 33 | ``` 34 | Invoke-WslCommand [-RawCommand] -Distribution [[-User] ] 35 | [-WorkingDirectory ] [-ShellType ] [-System] [-Graphical] -Remaining [-WhatIf] 36 | [-Confirm] [] 37 | ``` 38 | 39 | ### DistributionNameRaw 40 | 41 | ``` 42 | Invoke-WslCommand [-RawCommand] [-Name ] [[-User] ] [-WorkingDirectory ] 43 | [-ShellType ] [-System] [-Graphical] -Remaining [-WhatIf] [-Confirm] [] 44 | ``` 45 | 46 | ## DESCRIPTION 47 | 48 | The `Invoke-WslCommand` cmdlet executes a command in a WSL distribution, returning the output of the 49 | command as a string. The distribution to run the command in can be specified by name, or piped in 50 | from the `Get-WslDistribution` cmdlet. If no distribution is specified, the command is executed in 51 | the default distribution. 52 | 53 | This cmdlet will throw an exception if executing `wsl.exe` failed (e.g. if there is no distribution 54 | with the specified name), or if the command exited with an non-zero exit code. 55 | 56 | The command to execute can be specified in two ways. The default is using the **Command** parameter, 57 | where you provide the command in a single string, that will be passed to `/bin/sh -c` to execute it. 58 | 59 | Alternatively, you can use the **RawCommand** parameter to use all remaining parameters which do not 60 | match a known parameter for this cmdlet as the command. You can use the `--` separator to pass 61 | everything after to the WSL command. In this case, the command will be interpreted by the default 62 | shell configured in the distribution, rather than `/bin/sh`. See the examples for an example of this 63 | usage. 64 | 65 | This cmdlet wraps the functionality of `wsl.exe `. If using the **Graphical** parameter, it 66 | instead wraps `wslg.exe `. 67 | 68 | ## EXAMPLES 69 | 70 | ### EXAMPLE 1 71 | 72 | ```powershell 73 | Invoke-WslCommand "ls /etc" 74 | ``` 75 | 76 | This example runs a command in the default distribution. 77 | 78 | ### EXAMPLE 2 79 | 80 | ```powershell 81 | Invoke-WslCommand "whoami" -DistributionName "Ubuntu*" -User "root" 82 | ``` 83 | 84 | This example runs a command in all distributions whose name starts with "Ubuntu", as the "root" 85 | Linux user. 86 | 87 | ### EXAMPLE 3 88 | 89 | ```powershell 90 | Get-WslDistribution -Version 2 | Invoke-WslCommand 'echo $(whoami) in $WSL_DISTRO_NAME' 91 | ``` 92 | 93 | This example runs a command in all WSL2 distributions. Single quotes are used to prevent the dollar 94 | sign from being interpreted by PowerShell without needing to escape them, instead passing them to 95 | the Linux shell. 96 | 97 | ### EXAMPLE 4 98 | 99 | ```powershell 100 | Invoke-WslCommand -RawCommand echo Hello, $`(whoami`) 101 | ``` 102 | 103 | This example uses the **RawCommand** parameter, so all unrecognized remaining parameters will form 104 | the command, without needing to quote it. Characters that would be interpreted by PowerShell need to 105 | be escaped with a backtick. 106 | 107 | ### EXAMPLE 5 108 | 109 | ```powershell 110 | Invoke-WslCommand -RawCommand -- ls -u 111 | ``` 112 | 113 | This example uses the **RawCommand** parameter, and uses the `--` separator to use everything after 114 | it as part of the Linux command, even if it is a valid parameter for `Invoke-WslCommand`. This 115 | prevents `-u` from being interpreted as an alias for the **User** argument. 116 | 117 | ## PARAMETERS 118 | 119 | ### -Command 120 | 121 | Specifies the command to run, as a string that will be used with `/bin/sh -c`. 122 | 123 | ```yaml 124 | Type: String 125 | Parameter Sets: DistributionName, Distribution 126 | Aliases: 127 | 128 | Required: True 129 | Position: 1 130 | Default value: None 131 | Accept pipeline input: False 132 | Accept wildcard characters: False 133 | ``` 134 | 135 | ### -Distribution 136 | 137 | Specifies the distribution to run the command in. 138 | 139 | ```yaml 140 | Type: WslDistribution[] 141 | Parameter Sets: Distribution, DistributionRaw 142 | Aliases: 143 | 144 | Required: True 145 | Position: Named 146 | Default value: None 147 | Accept pipeline input: True (ByValue) 148 | Accept wildcard characters: False 149 | ``` 150 | 151 | ### -Graphical 152 | 153 | Specifies that the command should be executed using WSLg. Using this option prevents blocking the 154 | terminal while running GUI applications. 155 | 156 | This parameter requires at least WSL version 0.47.1. 157 | 158 | ```yaml 159 | Type: SwitchParameter 160 | Parameter Sets: (All) 161 | Aliases: 162 | 163 | Required: False 164 | Position: Named 165 | Default value: False 166 | Accept pipeline input: False 167 | Accept wildcard characters: False 168 | ``` 169 | 170 | ### -RawCommand 171 | 172 | Specifies that all remaining unrecognized parameters to this cmdlet are used as the command to run. 173 | 174 | ```yaml 175 | Type: SwitchParameter 176 | Parameter Sets: DistributionRaw, DistributionNameRaw 177 | Aliases: 178 | 179 | Required: True 180 | Position: Named 181 | Default value: False 182 | Accept pipeline input: False 183 | Accept wildcard characters: False 184 | ``` 185 | 186 | ### -Remaining 187 | 188 | Collects the remaining arguments for when the **RawCommand** parameter is supplied. 189 | 190 | ```yaml 191 | Type: String[] 192 | Parameter Sets: DistributionRaw, DistributionNameRaw 193 | Aliases: 194 | 195 | Required: True 196 | Position: Named 197 | Default value: None 198 | Accept pipeline input: False 199 | Accept wildcard characters: False 200 | ``` 201 | 202 | ### -ShellType 203 | 204 | Specifies the shell type to use for the command, either `Standard`, `Login`, or `None`. Note that if 205 | you are not using the **RawCommand** parameter, the command is still executed using `/bin/sh` on top 206 | of the selected shell type. 207 | 208 | This parameter requires at least WSL version 0.64.1. 209 | 210 | ```yaml 211 | Type: String 212 | Parameter Sets: (All) 213 | Aliases: st 214 | 215 | Required: False 216 | Position: Named 217 | Default value: None 218 | Accept pipeline input: False 219 | Accept wildcard characters: False 220 | ``` 221 | 222 | ### -System 223 | 224 | Specifies that the command should be executed in the system distribution. 225 | 226 | This parameter requires at least WSL version 0.47.1. 227 | 228 | ```yaml 229 | Type: SwitchParameter 230 | Parameter Sets: (All) 231 | Aliases: 232 | 233 | Required: False 234 | Position: Named 235 | Default value: False 236 | Accept pipeline input: False 237 | Accept wildcard characters: False 238 | ``` 239 | 240 | ### -User 241 | 242 | Specifies the Linux user to run the command as. If omitted, the default user for the distribution 243 | is used. 244 | 245 | ```yaml 246 | Type: String 247 | Parameter Sets: (All) 248 | Aliases: 249 | 250 | Required: False 251 | Position: 3 252 | Default value: None 253 | Accept pipeline input: False 254 | Accept wildcard characters: False 255 | ``` 256 | 257 | ### -WorkingDirectory 258 | 259 | Specifies the working directory to use for the command. Use `~` for the Linux user's home path. If 260 | the path starts with a `/` character, it will be interpreted as an absolute Linux path. Otherwise, 261 | the value must be a Windows path. 262 | 263 | ```yaml 264 | Type: String 265 | Parameter Sets: (All) 266 | Aliases: wd, cd 267 | 268 | Required: False 269 | Position: Named 270 | Default value: None 271 | Accept pipeline input: False 272 | Accept wildcard characters: False 273 | ``` 274 | 275 | ### -Confirm 276 | 277 | Prompts you for confirmation before running the cmdlet. 278 | 279 | ```yaml 280 | Type: SwitchParameter 281 | Parameter Sets: (All) 282 | Aliases: cf 283 | 284 | Required: False 285 | Position: Named 286 | Default value: None 287 | Accept pipeline input: False 288 | Accept wildcard characters: False 289 | ``` 290 | 291 | ### -WhatIf 292 | 293 | Shows what would happen if the cmdlet runs. 294 | The cmdlet is not run. 295 | 296 | ```yaml 297 | Type: SwitchParameter 298 | Parameter Sets: (All) 299 | Aliases: wi 300 | 301 | Required: False 302 | Position: Named 303 | Default value: None 304 | Accept pipeline input: False 305 | Accept wildcard characters: False 306 | ``` 307 | 308 | ### -Name 309 | 310 | Specifies the name of a distribution to run the command in. 311 | 312 | ```yaml 313 | Type: String[] 314 | Parameter Sets: DistributionName, DistributionNameRaw 315 | Aliases: DistributionName 316 | 317 | Required: False 318 | Position: Named 319 | Default value: None 320 | Accept pipeline input: True (ByValue) 321 | Accept wildcard characters: True 322 | ``` 323 | 324 | ### CommonParameters 325 | 326 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). 327 | 328 | ## INPUTS 329 | 330 | ### WslDistribution 331 | 332 | You can pipe an object retrieved by `Get-WslDistribution` to this cmdlet. 333 | 334 | ### System.String 335 | 336 | You can pipe a distribution name to this cmdlet. 337 | 338 | ## OUTPUTS 339 | 340 | ### System.String 341 | 342 | This cmdlet returns the output of the command, as text. If the **Graphical** parameter is used, 343 | no output will be returned, and the command finishes while the application may still be executing. 344 | 345 | ## NOTES 346 | 347 | ## RELATED LINKS 348 | 349 | [Get-WslDistribution](Get-WslDistribution.md) 350 | 351 | [Enter-WslDistribution](Enter-WslDistribution.md) 352 | -------------------------------------------------------------------------------- /docs/Remove-WslDistribution.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Wsl-help.xml 3 | Module Name: Wsl 4 | online version: https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Remove-WslDistribution.md 5 | schema: 2.0.0 6 | --- 7 | 8 | # Remove-WslDistribution 9 | 10 | ## SYNOPSIS 11 | 12 | Unregisters a WSL distribution. 13 | 14 | ## SYNTAX 15 | 16 | ### DistributionName 17 | 18 | ``` 19 | Remove-WslDistribution [-Name] [-WhatIf] [-Confirm] [] 20 | ``` 21 | 22 | ### Distribution 23 | 24 | ``` 25 | Remove-WslDistribution -Distribution [-WhatIf] [-Confirm] [] 26 | ``` 27 | 28 | ## DESCRIPTION 29 | 30 | The `Remove-WslDistribution` cmdlet unregisters a WSL distribution. The distribution to remove can 31 | be specified by name, or piped in from the `Get-WslDistribution` cmdlet. 32 | 33 | Removing a WSL distribution deletes its file system and all the data it contained. 34 | 35 | This cmdlet wraps the functionality of `wsl.exe --unregister`. 36 | 37 | ## EXAMPLES 38 | 39 | ### EXAMPLE 1 40 | 41 | ```powershell 42 | Remove-WslDistribution Ubuntu 43 | ``` 44 | 45 | This example unregisters the distribution named "Ubuntu". 46 | 47 | ### EXAMPLE 2 48 | 49 | ```powershell 50 | Remove-WslDistribution "Ubuntu*" 51 | ``` 52 | 53 | This example unregisters all distributions whose name starts with "Ubuntu". 54 | 55 | ### EXAMPLE 3 56 | 57 | ```powershell 58 | Get-WslDistribution -Version 1 | Remove-WslDistribution 59 | ``` 60 | 61 | This example unregisters all WSL1 distributions. 62 | 63 | ### EXAMPLE 4 64 | 65 | ```powershell 66 | Get-WslDistribution | Where-Object { $_.Name -ine "Ubuntu" } | Remove-WslDistribution 67 | ``` 68 | 69 | This example unregisters all distributions except the one named "Ubuntu". 70 | 71 | ## PARAMETERS 72 | 73 | ### -Distribution 74 | 75 | Specifies the distribution to be removed. 76 | 77 | ```yaml 78 | Type: WslDistribution[] 79 | Parameter Sets: Distribution 80 | Aliases: 81 | 82 | Required: True 83 | Position: Named 84 | Default value: None 85 | Accept pipeline input: True (ByValue) 86 | Accept wildcard characters: False 87 | ``` 88 | 89 | ### -Name 90 | 91 | Specifies the name of a distribution to be removed. 92 | 93 | ```yaml 94 | Type: String[] 95 | Parameter Sets: DistributionName 96 | Aliases: DistributionName 97 | 98 | Required: True 99 | Position: 1 100 | Default value: None 101 | Accept pipeline input: True (ByValue) 102 | Accept wildcard characters: True 103 | ``` 104 | 105 | ### -Confirm 106 | 107 | Prompts you for confirmation before running the cmdlet. 108 | 109 | ```yaml 110 | Type: SwitchParameter 111 | Parameter Sets: (All) 112 | Aliases: cf 113 | 114 | Required: False 115 | Position: Named 116 | Default value: None 117 | Accept pipeline input: False 118 | Accept wildcard characters: False 119 | ``` 120 | 121 | ### -WhatIf 122 | 123 | Shows what would happen if the cmdlet runs. 124 | The cmdlet is not run. 125 | 126 | ```yaml 127 | Type: SwitchParameter 128 | Parameter Sets: (All) 129 | Aliases: wi 130 | 131 | Required: False 132 | Position: Named 133 | Default value: None 134 | Accept pipeline input: False 135 | Accept wildcard characters: False 136 | ``` 137 | 138 | ### CommonParameters 139 | 140 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). 141 | 142 | ## INPUTS 143 | 144 | ### WslDistribution 145 | 146 | You can pipe an object retrieved by `Get-WslDistribution` to this cmdlet. 147 | 148 | ### System.String 149 | 150 | You can pipe a distribution name to this cmdlet. 151 | 152 | ## OUTPUTS 153 | 154 | ## NOTES 155 | 156 | ## RELATED LINKS 157 | 158 | [Get-WslDistribution](Get-WslDistribution.md) 159 | -------------------------------------------------------------------------------- /docs/Set-WslDistribution.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Wsl-help.xml 3 | Module Name: Wsl 4 | online version: https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Set-WslDistribution.md 5 | schema: 2.0.0 6 | --- 7 | 8 | # Set-WslDistribution 9 | 10 | ## SYNOPSIS 11 | 12 | Changes the settings of a WSL distribution. 13 | 14 | ## SYNTAX 15 | 16 | ### DistributionName 17 | 18 | ``` 19 | Set-WslDistribution [-Name] [-Version ] [-Default] [-Passthru] [-WhatIf] [-Confirm] 20 | [] 21 | ``` 22 | 23 | ### Distribution 24 | 25 | ``` 26 | Set-WslDistribution -Distribution [-Version ] [-Default] [-Passthru] [-WhatIf] 27 | [-Confirm] [] 28 | ``` 29 | 30 | ## DESCRIPTION 31 | 32 | The `Set-WslDistribution` cmdlet changes the settings of a WSL distribution. The distribution can be 33 | specified by name, or piped in from the `Get-WslDistribution` cmdlet. 34 | 35 | This cmdlet wraps the functionality of `wsl.exe --set-default` and `wsl.exe --set-version`. 36 | 37 | ## EXAMPLES 38 | 39 | ### EXAMPLE 1 40 | 41 | ```powershell 42 | Set-WslDistribution Ubuntu -Default 43 | ``` 44 | 45 | This example makes the distribution named "Ubuntu" the default. 46 | 47 | ### EXAMPLE 2 48 | 49 | ```powershell 50 | Get-WslDistribution -Version 1 | Set-WslDistribution -Version 2 -Passthru 51 | ``` 52 | 53 | ```Output 54 | Name State Version Default 55 | ---- ----- ------- ------- 56 | Ubuntu-18.04 Running 2 False 57 | Debian Stopped 2 False 58 | ``` 59 | 60 | This example converts all version 1 distributions to version 2. It uses the **Passthru** parameter 61 | to return the WslDistribution objects for the affected distributions. 62 | 63 | ## PARAMETERS 64 | 65 | ### -Default 66 | 67 | Specifies that the distribution should be made the default distribution. If the input specifies 68 | multiple distributions, the last one processed will be the default after the command finishes. 69 | 70 | ```yaml 71 | Type: SwitchParameter 72 | Parameter Sets: (All) 73 | Aliases: 74 | 75 | Required: False 76 | Position: Named 77 | Default value: False 78 | Accept pipeline input: False 79 | Accept wildcard characters: False 80 | ``` 81 | 82 | ### -Distribution 83 | 84 | Specifies the distribution whose settings to change. 85 | 86 | ```yaml 87 | Type: WslDistribution[] 88 | Parameter Sets: Distribution 89 | Aliases: 90 | 91 | Required: True 92 | Position: Named 93 | Default value: None 94 | Accept pipeline input: True (ByValue) 95 | Accept wildcard characters: False 96 | ``` 97 | 98 | ### -Name 99 | 100 | Specifies the name of a distribution whose settings to change. 101 | 102 | ```yaml 103 | Type: String[] 104 | Parameter Sets: DistributionName 105 | Aliases: DistributionName 106 | 107 | Required: True 108 | Position: 1 109 | Default value: None 110 | Accept pipeline input: True (ByValue) 111 | Accept wildcard characters: True 112 | ``` 113 | 114 | ### -Passthru 115 | 116 | Specifies that a WslDistribution object is to be passed through to the pipeline representing the 117 | distribution whose settings were changed. 118 | 119 | ```yaml 120 | Type: SwitchParameter 121 | Parameter Sets: (All) 122 | Aliases: 123 | 124 | Required: False 125 | Position: Named 126 | Default value: False 127 | Accept pipeline input: False 128 | Accept wildcard characters: False 129 | ``` 130 | 131 | ### -Version 132 | 133 | Specifies the WSL distribution version to convert the distribution to, either 1 or 2. Converting 134 | a distribution may take several minutes. 135 | 136 | ```yaml 137 | Type: Int32 138 | Parameter Sets: (All) 139 | Aliases: 140 | 141 | Required: False 142 | Position: Named 143 | Default value: 0 144 | Accept pipeline input: False 145 | Accept wildcard characters: False 146 | ``` 147 | 148 | ### -Confirm 149 | 150 | Prompts you for confirmation before running the cmdlet. 151 | 152 | ```yaml 153 | Type: SwitchParameter 154 | Parameter Sets: (All) 155 | Aliases: cf 156 | 157 | Required: False 158 | Position: Named 159 | Default value: None 160 | Accept pipeline input: False 161 | Accept wildcard characters: False 162 | ``` 163 | 164 | ### -WhatIf 165 | 166 | Shows what would happen if the cmdlet runs. 167 | The cmdlet is not run. 168 | 169 | ```yaml 170 | Type: SwitchParameter 171 | Parameter Sets: (All) 172 | Aliases: wi 173 | 174 | Required: False 175 | Position: Named 176 | Default value: None 177 | Accept pipeline input: False 178 | Accept wildcard characters: False 179 | ``` 180 | 181 | ### CommonParameters 182 | 183 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). 184 | 185 | ## INPUTS 186 | 187 | ### WslDistribution 188 | 189 | You can pipe an object retrieved by `Get-WslDistribution` to this cmdlet. 190 | 191 | ### System.String 192 | 193 | You can pipe a distribution name to this cmdlet. 194 | 195 | ## OUTPUTS 196 | 197 | ### None by default; WslDistribution if PassThru is specified 198 | 199 | See `Get-WslDistribution` for more information. 200 | 201 | ## NOTES 202 | 203 | ## RELATED LINKS 204 | 205 | [Get-WslDistribution](Get-WslDistribution.md) 206 | -------------------------------------------------------------------------------- /docs/Stop-Wsl.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Wsl-help.xml 3 | Module Name: Wsl 4 | online version: https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Stop-Wsl.md 5 | schema: 2.0.0 6 | --- 7 | 8 | # Stop-Wsl 9 | 10 | ## SYNOPSIS 11 | 12 | Terminates all WSL distributions, and shuts down the WSL2 lightweight utility VM. 13 | 14 | ## SYNTAX 15 | 16 | ``` 17 | Stop-Wsl [-WhatIf] [-Confirm] [] 18 | ``` 19 | 20 | ## DESCRIPTION 21 | 22 | The `Stop-Wsl` cmdlet terminates all WSL distributions, and shuts down the WSL2 lightweight utility 23 | VM. 24 | 25 | This cmdlet wraps the functionality of `wsl.exe --shutdown`. 26 | 27 | ## EXAMPLES 28 | 29 | ### EXAMPLE 1 30 | 31 | ```powershell 32 | Stop-Wsl 33 | ``` 34 | 35 | This example terminates all WSL distributions, and shuts down the WSL2 lightweight utility VM. 36 | 37 | ## PARAMETERS 38 | 39 | ### -Confirm 40 | 41 | Prompts you for confirmation before running the cmdlet. 42 | 43 | ```yaml 44 | Type: SwitchParameter 45 | Parameter Sets: (All) 46 | Aliases: cf 47 | 48 | Required: False 49 | Position: Named 50 | Default value: None 51 | Accept pipeline input: False 52 | Accept wildcard characters: False 53 | ``` 54 | 55 | ### -WhatIf 56 | 57 | Shows what would happen if the cmdlet runs. 58 | The cmdlet is not run. 59 | 60 | ```yaml 61 | Type: SwitchParameter 62 | Parameter Sets: (All) 63 | Aliases: wi 64 | 65 | Required: False 66 | Position: Named 67 | Default value: None 68 | Accept pipeline input: False 69 | Accept wildcard characters: False 70 | ``` 71 | 72 | ### CommonParameters 73 | 74 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). 75 | 76 | ## INPUTS 77 | 78 | ## OUTPUTS 79 | 80 | ## NOTES 81 | 82 | ## RELATED LINKS 83 | -------------------------------------------------------------------------------- /docs/Stop-WslDistribution.md: -------------------------------------------------------------------------------- 1 | --- 2 | external help file: Wsl-help.xml 3 | Module Name: Wsl 4 | online version: https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Stop-WslDistribution.md 5 | schema: 2.0.0 6 | --- 7 | 8 | # Stop-WslDistribution 9 | 10 | ## SYNOPSIS 11 | 12 | Terminates a WSL distribution. 13 | 14 | ## SYNTAX 15 | 16 | ### DistributionName 17 | 18 | ``` 19 | Stop-WslDistribution [-Name] [-Passthru] [-WhatIf] [-Confirm] [] 20 | ``` 21 | 22 | ### Distribution 23 | 24 | ``` 25 | Stop-WslDistribution -Distribution [-Passthru] [-WhatIf] [-Confirm] [] 26 | ``` 27 | 28 | ## DESCRIPTION 29 | 30 | The `Stop-WslDistribution` cmdlet terminates a WSL distribution. The distribution to stop can be 31 | specified by name, or piped in from the `Get-WslDistribution` cmdlet. 32 | 33 | This cmdlet wraps the functionality of `wsl.exe --terminate`. 34 | 35 | ## EXAMPLES 36 | 37 | ### EXAMPLE 1 38 | 39 | ```powershell 40 | Stop-WslDistribution "Ubuntu" 41 | ``` 42 | 43 | This example stops the distribution named "Ubuntu". 44 | 45 | ### EXAMPLE 2 46 | 47 | ```powershell 48 | Stop-WslDistribution "Ubuntu*" 49 | ``` 50 | 51 | This example terminates all distributions whose name starts with "Ubuntu". 52 | 53 | ### EXAMPLE 3 54 | 55 | ```powershell 56 | Get-WslDistribution -Version 2 | Stop-WslDistribution -Passthru 57 | ``` 58 | 59 | ```Output 60 | Name State Version Default 61 | ---- ----- ------- ------- 62 | Ubuntu Stopped 2 True 63 | Alpine Stopped 2 False 64 | ``` 65 | 66 | This example terminates all WSL2 distributions. It uses the **Passthru** parameter to return the 67 | WslDistribution objects for the affected distributions. 68 | 69 | ## PARAMETERS 70 | 71 | ### -Distribution 72 | 73 | Specifies the distribution to be terminated. 74 | 75 | ```yaml 76 | Type: WslDistribution[] 77 | Parameter Sets: Distribution 78 | Aliases: 79 | 80 | Required: True 81 | Position: Named 82 | Default value: None 83 | Accept pipeline input: True (ByValue) 84 | Accept wildcard characters: False 85 | ``` 86 | 87 | ### -Name 88 | 89 | Specifies the name of a distribution to be terminated. 90 | 91 | ```yaml 92 | Type: String[] 93 | Parameter Sets: DistributionName 94 | Aliases: DistributionName 95 | 96 | Required: True 97 | Position: 1 98 | Default value: None 99 | Accept pipeline input: True (ByValue) 100 | Accept wildcard characters: True 101 | ``` 102 | 103 | ### -Passthru 104 | 105 | Specifies that a WslDistribution object is to be passed through to the pipeline representing the 106 | distribution to be shutdown. 107 | 108 | ```yaml 109 | Type: SwitchParameter 110 | Parameter Sets: (All) 111 | Aliases: 112 | 113 | Required: False 114 | Position: Named 115 | Default value: False 116 | Accept pipeline input: False 117 | Accept wildcard characters: False 118 | ``` 119 | 120 | ### -Confirm 121 | 122 | Prompts you for confirmation before running the cmdlet. 123 | 124 | ```yaml 125 | Type: SwitchParameter 126 | Parameter Sets: (All) 127 | Aliases: cf 128 | 129 | Required: False 130 | Position: Named 131 | Default value: None 132 | Accept pipeline input: False 133 | Accept wildcard characters: False 134 | ``` 135 | 136 | ### -WhatIf 137 | 138 | Shows what would happen if the cmdlet runs. 139 | The cmdlet is not run. 140 | 141 | ```yaml 142 | Type: SwitchParameter 143 | Parameter Sets: (All) 144 | Aliases: wi 145 | 146 | Required: False 147 | Position: Named 148 | Default value: None 149 | Accept pipeline input: False 150 | Accept wildcard characters: False 151 | ``` 152 | 153 | ### CommonParameters 154 | 155 | This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). 156 | 157 | ## INPUTS 158 | 159 | ### WslDistribution 160 | 161 | You can pipe an object retrieved by `Get-WslDistribution` to this cmdlet. 162 | 163 | ### System.String 164 | 165 | You can pipe a distribution name to this cmdlet. 166 | 167 | ## OUTPUTS 168 | 169 | ### None by default; WslDistribution if PassThru is specified 170 | 171 | See `Get-WslDistribution` for more information. 172 | 173 | ## NOTES 174 | 175 | ## RELATED LINKS 176 | 177 | [Get-WslDistribution](Get-WslDistribution.md) 178 | -------------------------------------------------------------------------------- /docs/Wsl.md: -------------------------------------------------------------------------------- 1 | --- 2 | Module Name: Wsl 3 | Module Guid: 5aebb9a8-dbf6-44d3-8c6c-dc343d4e3f0a 4 | Download Help Link: 5 | Help Version: 2.0.0.0 6 | Locale: en-US 7 | --- 8 | 9 | # Wsl Module 10 | 11 | ## Description 12 | 13 | The Wsl module provides cmdlets that let you manage the Windows Subsystem for Linux and its 14 | distributions. 15 | 16 | ## Wsl Cmdlets 17 | 18 | ### [Enter-WslDistribution](Enter-WslDistribution.md) 19 | 20 | Starts an interactive session in a WSL distribution. 21 | 22 | ### [Export-WslDistribution](Export-WslDistribution.md) 23 | 24 | Exports a WSL distribution to a gzipped tarball or VHD file. 25 | 26 | ### [Get-WslDistribution](Get-WslDistribution.md) 27 | 28 | Gets information about WSL distributions installed for the current user. 29 | 30 | ### [Get-WslDistributionOnline](Get-WslDistributionOnline.md) 31 | 32 | Gets information about WSL distributions available from online sources. 33 | 34 | ### [Get-WslVersion](Get-WslVersion.md) 35 | 36 | Gets version information about the Windows Subsystem for Linux and its components. 37 | 38 | ### [Import-WslDistribution](Import-WslDistribution.md) 39 | 40 | Imports a WSL distribution from a gzipped tarball or VHD file. 41 | 42 | ### [Invoke-WslCommand](Invoke-WslCommand.md) 43 | 44 | Runs a command in a WSL distribution. 45 | 46 | ### [Remove-WslDistribution](Remove-WslDistribution.md) 47 | 48 | Unregisters a WSL distribution. 49 | 50 | ### [Set-WslDistribution](Set-WslDistribution.md) 51 | 52 | Changes the settings of a WSL distribution. 53 | 54 | ### [Stop-Wsl](Stop-Wsl.md) 55 | 56 | Terminates all WSL distributions, and shuts down the WSL2 lightweight utility VM. 57 | 58 | ### [Stop-WslDistribution](Stop-WslDistribution.md) 59 | 60 | Terminates a WSL distribution. 61 | --------------------------------------------------------------------------------