Wsl-help.xml
|
<?xml version="1.0" encoding="utf-8"?>
<helpItems schema="maml" xmlns="http://msh"> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Enter-WslDistribution</command:name> <command:verb>Enter</command:verb> <command:noun>WslDistribution</command:noun> <maml:description> <maml:para>Starts an interactive session in a WSL distribution.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `Enter-WslDistribution` cmdlet starts an interactive shell in a WSL distribution. During the session, all commands that you type run inside the WSL distribution. You can have only one interactive session at a time.</maml:para> <maml:para>The distribution to enter can be specified by name, or piped in from the `Get-WslDistribution` cmdlet. If no distribution is specified, the default distribution will be used.</maml:para> <maml:para>This cmdlet will throw an exception if executing `wsl.exe` failed (e.g. if there is no distribution with the specified name), or if the session exited with an non-zero exit code.</maml:para> <maml:para>This cmdlet wraps the functionality of `wsl.exe` without specifying a command.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Enter-WslDistribution</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>User</maml:name> <maml:description> <maml:para>Specifies the Linux user to run the interactive session as. If omitted, the default user for the distribution is used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Distribution</maml:name> <maml:description> <maml:para>Specifies the distribution to enter.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslDistribution</command:parameterValue> <dev:type> <maml:name>WslDistribution</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="st"> <maml:name>ShellType</maml:name> <maml:description> <maml:para>Specifies the shell type to use for the interactive session, either `Standard` or `Login`.</maml:para> <maml:para>This parameter requires at least WSL version 0.64.1.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>System</maml:name> <maml:description> <maml:para>Specifies that the interactive session should use the system distribution.</maml:para> <maml:para>This parameter requires at least WSL version 0.47.1.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wd, cd"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>Specifies the working directory to use for the session. Use `~` for the Linux user's home path. If the path starts with a `/` character, it will be interpreted as an absolute Linux path. Otherwise, the value must be a Windows path.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Enter-WslDistribution</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of a distribution to enter. Unlike with other cmdlets in this module, this parameter does not accept wildcards.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>User</maml:name> <maml:description> <maml:para>Specifies the Linux user to run the interactive session as. If omitted, the default user for the distribution is used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="st"> <maml:name>ShellType</maml:name> <maml:description> <maml:para>Specifies the shell type to use for the interactive session, either `Standard` or `Login`.</maml:para> <maml:para>This parameter requires at least WSL version 0.64.1.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>System</maml:name> <maml:description> <maml:para>Specifies that the interactive session should use the system distribution.</maml:para> <maml:para>This parameter requires at least WSL version 0.47.1.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wd, cd"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>Specifies the working directory to use for the session. Use `~` for the Linux user's home path. If the path starts with a `/` character, it will be interpreted as an absolute Linux path. Otherwise, the value must be a Windows path.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Distribution</maml:name> <maml:description> <maml:para>Specifies the distribution to enter.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslDistribution</command:parameterValue> <dev:type> <maml:name>WslDistribution</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of a distribution to enter. Unlike with other cmdlets in this module, this parameter does not accept wildcards.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="st"> <maml:name>ShellType</maml:name> <maml:description> <maml:para>Specifies the shell type to use for the interactive session, either `Standard` or `Login`.</maml:para> <maml:para>This parameter requires at least WSL version 0.64.1.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>System</maml:name> <maml:description> <maml:para>Specifies that the interactive session should use the system distribution.</maml:para> <maml:para>This parameter requires at least WSL version 0.47.1.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>User</maml:name> <maml:description> <maml:para>Specifies the Linux user to run the interactive session as. If omitted, the default user for the distribution is used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wd, cd"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>Specifies the working directory to use for the session. Use `~` for the Linux user's home path. If the path starts with a `/` character, it will be interpreted as an absolute Linux path. Otherwise, the value must be a Windows path.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>WslDistribution</maml:name> </dev:type> <maml:description> <maml:para>You can pipe an object retrieved by `Get-WslDistribution` to this cmdlet.</maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>You can pipe a distribution name to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues /> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Enter-WslDistribution</dev:code> <dev:remarks> <maml:para>This example starts a shell in the default distribution.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Enter-WslDistribution Ubuntu root -WorkingDirectory "~"</dev:code> <dev:remarks> <maml:para>This example starts a shell in the distribution named "Ubuntu", using the "root" user. The starting directory will be the Linux user's home directory.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Import-WslDistribution D:\backup\Alpine.tar.gz D:\wsl | Enter-WslDistribution</dev:code> <dev:remarks> <maml:para>This example imports a WSL distribution, and immediately starts an interactive session in that distribution.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Enter-WslDistribution.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-WslDistribution</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Invoke-WslCommand</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Export-WslDistribution</command:name> <command:verb>Export</command:verb> <command:noun>WslDistribution</command:noun> <maml:description> <maml:para>Exports a WSL distribution to a gzipped tarball or VHD file.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `Export-WslDistribution` cmdlet exports a WSL distributions to a gzipped tarball or VHD file. The distribution to export can be specified by name, or piped in from the `Get-WslDistribution` cmdlet.</maml:para> <maml:para>If the Destination parameter is an existing directory, the name of the distribution, with the extension `.tar.gz` or `.vhdx`, will be used as the file name. This allows you to export multiple distributions to a directory using a single command.</maml:para> <maml:para>The default behavior is to export the distribution as a gzipped tarball, unless the Destination is a file name ending in `.vhdx`. This format can also be manually selected using the Format parameter.</maml:para> <maml:para>This cmdlet wraps the functionality of `wsl.exe --export`.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Export-WslDistribution</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Destination</maml:name> <maml:description> <maml:para>Specifies the destination directory or file name where the exported distribution will be stored.</maml:para> <maml:para>If you specify an existing directory as the destination, a file will be created in that directory using the distribution name and the extension `.tar.gz` or `.vhdx` depending on the value of the Format parameter.</maml:para> <maml:para>If you specify a non-existing path, that path will be used verbatim as the file for the exported distribution.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Distribution</maml:name> <maml:description> <maml:para>Specifies the distribution to be exported.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslDistribution[]</command:parameterValue> <dev:type> <maml:name>WslDistribution[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="fmt"> <maml:name>Format</maml:name> <maml:description> <maml:para>Specifies the format of the exported distribution. `Auto`, which is the default, exports as a gzipped tarball, unless the Destination is a file name ending in `.vhdx`, in which case VHD format is used; `Tar` exports as a gzipped tarball; and `Vhd` exports as a Virtual Hard Disk.</maml:para> <maml:para>Exporting as a VHD is only possible for WSL2 distributions.</maml:para> <maml:para>Exporting VHDs requires at least WSL version 0.58.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Auto</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Tar</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Vhd</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">WslExportFormat</command:parameterValue> <dev:type> <maml:name>WslExportFormat</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Export-WslDistribution</maml:name> <command:parameter required="true" variableLength="true" globbing="true" pipelineInput="True (ByValue)" position="1" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of a distribution to be exported.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Destination</maml:name> <maml:description> <maml:para>Specifies the destination directory or file name where the exported distribution will be stored.</maml:para> <maml:para>If you specify an existing directory as the destination, a file will be created in that directory using the distribution name and the extension `.tar.gz` or `.vhdx` depending on the value of the Format parameter.</maml:para> <maml:para>If you specify a non-existing path, that path will be used verbatim as the file for the exported distribution.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="fmt"> <maml:name>Format</maml:name> <maml:description> <maml:para>Specifies the format of the exported distribution. `Auto`, which is the default, exports as a gzipped tarball, unless the Destination is a file name ending in `.vhdx`, in which case VHD format is used; `Tar` exports as a gzipped tarball; and `Vhd` exports as a Virtual Hard Disk.</maml:para> <maml:para>Exporting as a VHD is only possible for WSL2 distributions.</maml:para> <maml:para>Exporting VHDs requires at least WSL version 0.58.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Auto</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Tar</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Vhd</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">WslExportFormat</command:parameterValue> <dev:type> <maml:name>WslExportFormat</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Destination</maml:name> <maml:description> <maml:para>Specifies the destination directory or file name where the exported distribution will be stored.</maml:para> <maml:para>If you specify an existing directory as the destination, a file will be created in that directory using the distribution name and the extension `.tar.gz` or `.vhdx` depending on the value of the Format parameter.</maml:para> <maml:para>If you specify a non-existing path, that path will be used verbatim as the file for the exported distribution.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Distribution</maml:name> <maml:description> <maml:para>Specifies the distribution to be exported.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslDistribution[]</command:parameterValue> <dev:type> <maml:name>WslDistribution[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="fmt"> <maml:name>Format</maml:name> <maml:description> <maml:para>Specifies the format of the exported distribution. `Auto`, which is the default, exports as a gzipped tarball, unless the Destination is a file name ending in `.vhdx`, in which case VHD format is used; `Tar` exports as a gzipped tarball; and `Vhd` exports as a Virtual Hard Disk.</maml:para> <maml:para>Exporting as a VHD is only possible for WSL2 distributions.</maml:para> <maml:para>Exporting VHDs requires at least WSL version 0.58.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslExportFormat</command:parameterValue> <dev:type> <maml:name>WslExportFormat</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="true" pipelineInput="True (ByValue)" position="1" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of a distribution to be exported.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>WslDistribution</maml:name> </dev:type> <maml:description> <maml:para>You can pipe an object retrieved by `Get-WslDistribution` to this cmdlet.</maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>You can pipe a distribution name to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.IO.FileInfo</maml:name> </dev:type> <maml:description> <maml:para>The `FileInfo` object contains information about the file containing the exported distribution.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Export-WslDistribution "Ubuntu" D:\backup.tar.gz Directory: D:\ Mode LastWriteTime Length Name ---- ------------- ------ ---- -a--- 9/8/2023 2:56 PM 156843008000 backup.tar.gz</dev:code> <dev:remarks> <maml:para>This example exports the distribution named "Ubuntu" to a file named `D:\backup.tar.gz`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Export-WslDistribution "Ubuntu" D:\backup.vhdx Directory: D:\ Mode LastWriteTime Length Name ---- ------------- ------ ---- -a--- 9/8/2023 12:51 PM 171853217792 backup.vhdx</dev:code> <dev:remarks> <maml:para>This example exports the distribution named "Ubuntu" to a file named `D:\backup.vhdx`, which is a VHD, not a gzipped tarball. This requires the distribution to use WSL2.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>New-Item D:\backup -ItemType Directory Export-WslDistribution "Ubuntu*" D:\backup Directory: D:\backup Mode LastWriteTime Length Name ---- ------------- ------ ---- -a--- 9/8/2023 2:56 PM 156843008000 Ubuntu.tar.gz -a--- 9/8/2023 2:56 PM 1336043520 Ubuntu-22.04.tar.gz</dev:code> <dev:remarks> <maml:para>This example exports all distributions whose name starts with Ubuntu to a directory named `D:\backup`. Separate `.tar.gz` files will be created for each distribution.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title> <dev:code>Get-WslDistribution -Version 2 | Export-WslDistribution -Destination D:\backup -Format "Vhd" Directory: D:\backup Mode LastWriteTime Length Name ---- ------------- ------ ---- -a--- 9/8/2023 12:51 PM 62914560 Alpine.vhdx -a--- 9/8/2023 12:51 PM 171853217792 Ubuntu.vhdx</dev:code> <dev:remarks> <maml:para>This example exports all WSL2 distributions to a directory named `D:\backup`, using VHD format.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Export-WslDistribution.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-WslDistribution</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Import-WslDistribution</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-WslDistribution</command:name> <command:verb>Get</command:verb> <command:noun>WslDistribution</command:noun> <maml:description> <maml:para>Gets information about WSL distributions installed for the current user.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `Get-WslDistribution` cmdlet gets information about all the WSL distributions installed for the current user.</maml:para> <maml:para>You can filter the output using the parameters of this cmdlet. Use the Name parameter to only return distributions with the specified name, supporting wildcards. Use the Default parameter to return only the default distribution. The State parameter filters by states such as `Running` or `Stopped`, and the Version parameter selects only WSL1 or WSL2 distributions.</maml:para> <maml:para>This cmdlet wraps the functionality of `wsl.exe --list --verbose`.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-WslDistribution</maml:name> <command:parameter required="false" variableLength="true" globbing="true" pipelineInput="True (ByValue)" position="1" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of a distribution to get detailed information about.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>State</maml:name> <maml:description> <maml:para>Specifies the distribution state (`Stopped`, `Running`, `Installing`, `Uninstalling`, or `Converting`) to filter the results by. Only distributions in the specified state are returned.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Stopped</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Running</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Installing</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Uninstalling</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Converting</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">WslDistributionState</command:parameterValue> <dev:type> <maml:name>WslDistributionState</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>Version</maml:name> <maml:description> <maml:para>Specifies the WSL distribution version (1 or 2) to filter the results by. Only distributions using either WSL1 or WSL2 are returned.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>0</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Default</maml:name> <maml:description> <maml:para>Specifies that only the default distribution should be returned. If combined with other filter parameters, the default distribution is only returned if it also matches the other filters; otherwise, nothing is returned.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Default</maml:name> <maml:description> <maml:para>Specifies that only the default distribution should be returned. If combined with other filter parameters, the default distribution is only returned if it also matches the other filters; otherwise, nothing is returned.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="true" pipelineInput="True (ByValue)" position="1" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of a distribution to get detailed information about.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>State</maml:name> <maml:description> <maml:para>Specifies the distribution state (`Stopped`, `Running`, `Installing`, `Uninstalling`, or `Converting`) to filter the results by. Only distributions in the specified state are returned.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslDistributionState</command:parameterValue> <dev:type> <maml:name>WslDistributionState</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>Version</maml:name> <maml:description> <maml:para>Specifies the WSL distribution version (1 or 2) to filter the results by. Only distributions using either WSL1 or WSL2 are returned.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>0</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>You can pipe a distribution name to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>WslDistribution</maml:name> </dev:type> <maml:description> <maml:para>This cmdlet returns objects that represent the distributions on the computer. This object has the following properties:</maml:para> <maml:para>- `Name`: The distribution name.</maml:para> <maml:para>- `State`: The current state of the distribution (`Stopped`, `Running`, `Installing`, `Uninstalling`, or `Converting`).</maml:para> <maml:para>- `Version`: Indicates whether this distribution uses WSL1 or WSL2.</maml:para> <maml:para>- `Default`: A boolean that indicates whether this is the default distribution.</maml:para> <maml:para>- `Guid`: The identifier for the distribution used in the registry and by WSL internally.</maml:para> <maml:para>- `BasePath`: The install location of the distribution.</maml:para> <maml:para>- `FileSystemPath`: The path to use to access the distribution's file system, in the form `\wsl.localhost\distro`.</maml:para> <maml:para>- `VhdPath`: For WSL2 distributions, the path to the VHD file containing the distribution's file system.</maml:para> <maml:para></maml:para> <maml:para>The `Guid`, `BasePath`, and `VhdPath` properties will be null if this cmdlet was invoked from Linux PowerShell inside a WSL distribution.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Get-WslDistribution Name State Version Default ---- ----- ------- ------- Ubuntu Stopped 2 True Ubuntu-22.04 Running 1 False Alpine Running 2 False Debian Stopped 1 False</dev:code> <dev:remarks> <maml:para>This example lists all WSL distributions.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Get-WslDistribution -Default Name State Version Default ---- ----- ------- ------- Ubuntu Stopped 2 True</dev:code> <dev:remarks> <maml:para>This example retrieves only the default distribution.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Get-WslDistribution -Version 2 -State Running Name State Version Default ---- ----- ------- ------- Alpine Running 2 False</dev:code> <dev:remarks> <maml:para>This example gets only those distribution which are running, and are using WSL2.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title> <dev:code>Get-WslDistribution "Ubuntu*" | Stop-WslDistribution</dev:code> <dev:remarks> <maml:para>This example get all distributions whose name starts with `Ubuntu`, and then terminates them.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 5 --------------------------</maml:title> <dev:code>Get-Content "distributions.txt" | Get-WslDistribution Name State Version Default ---- ----- ------- ------- Ubuntu Stopped 2 True Debian Stopped 1 False</dev:code> <dev:remarks> <maml:para>This example pipes the contents of a file, containing the names of distributions, to the `Get-WslDistribution` cmdlet. Only the distributions that are listed in the file are returned.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Get-WslDistribution.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-WslDistributionOnline</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Enter-WslDistribution</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Export-WslDistribution</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Import-WslDistribution</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Invoke-WslCommand</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Remove-WslDistribution</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Set-WslDistribution</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Stop-WslDistribution</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-WslDistributionOnline</command:name> <command:verb>Get</command:verb> <command:noun>WslDistributionOnline</command:noun> <maml:description> <maml:para>Gets information about WSL distributions available from online sources.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `Get-WslDistributionOnline` cmdlet gets information about all the WSL distributions available from online sources.</maml:para> <maml:para>This cmdlet wraps the functionality of `wsl.exe --list --online`.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-WslDistributionOnline</maml:name> </command:syntaxItem> </command:syntax> <command:parameters /> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>WslDistributionOnline</maml:name> </dev:type> <maml:description> <maml:para>This cmdlet returns objects that represent the distributions available from online sources. This object has the following properties:</maml:para> <maml:para>- `Name`: The distribution name that can be used to install it using `wsl.exe --install`</maml:para> <maml:para>- `FriendlyName`: The Friendly Name for the distribution.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Get-WslDistributionOnline Name FriendlyName ---- ------------ Ubuntu Ubuntu Debian Debian GNU/Linux kali-linux Kali Linux Rolling Ubuntu-18.04 Ubuntu 18.04 LTS Ubuntu-20.04 Ubuntu 20.04 LTS Ubuntu-22.04 Ubuntu 22.04 LTS OracleLinux_7_9 Oracle Linux 7.9 OracleLinux_8_7 Oracle Linux 8.7 OracleLinux_9_1 Oracle Linux 9.1 openSUSE-Leap-15.5 openSUSE Leap 15.5 SUSE-Linux-Enterprise-Server-15-SP4 SUSE Linux Enterprise Server 15 SP4 SUSE-Linux-Enterprise-15-SP5 SUSE Linux Enterprise 15 SP5 openSUSE-Tumbleweed openSUSE Tumbleweed</dev:code> <dev:remarks> <maml:para>This example lists all WSL distributions available from online sources.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Get-WslDistributionOnline.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-WslDistribution</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-WslVersion</command:name> <command:verb>Get</command:verb> <command:noun>WslVersion</command:noun> <maml:description> <maml:para>Gets version information about the Windows Subsystem for Linux and its components.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `Get-WslVersion` cmdlet gets the version of the WSL store app, as well as other WSL components such as the Linux kernel and WSLg.</maml:para> <maml:para>The returned information includes the default distribution version, which is not a version number, but a number that indicates whether WSL1 or WSL2 is used by default for newly registered distributions.</maml:para> <maml:para>If WSL is not installed from the Microsoft Store, and the inbox version of WSL is used, all the versions will be null, except for the `Windows` version and `DefaultDistroVersion`.</maml:para> <maml:para>This cmdlet wraps the functionality of `wsl.exe --version`.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-WslVersion</maml:name> </command:syntaxItem> </command:syntax> <command:parameters /> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>WslVersionInfo</maml:name> </dev:type> <maml:description> <maml:para>The cmdlet returns an object whose properties represent the versions of WSL components. It has the following properties:</maml:para> <maml:para>- `Wsl`: The version of the WSL app from the Microsoft Store.</maml:para> <maml:para>- `Kernel`: The Linux kernel version.</maml:para> <maml:para>- `WslG`: The version of the WSLg component.</maml:para> <maml:para>- `Msrdc`: The version of the Microsoft Remote Desktop Client.</maml:para> <maml:para>- `Direct3D`: The version of the Direct3D component.</maml:para> <maml:para>- `DXCore`: The version of the DXCore component.</maml:para> <maml:para>- `Windows`: The Windows operating system version.</maml:para> <maml:para>- `DefaultDistroVersion`: The version that newly registered distributions will use. `1` for WSL1, and `2` for WSL2.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Get-WslVersion Wsl : 1.2.5.0 Kernel : 5.15.90.1 WslG : 1.0.51 Msrdc : 1.2.3770 Direct3D : 1.608.2 DXCore : 10.0.25131.1002 Windows : 10.0.22621.2215 DefaultDistroVersion : 2</dev:code> <dev:remarks> <maml:para>This example gets information about the installed version of WSL.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Get-WslVersion.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Import-WslDistribution</command:name> <command:verb>Import</command:verb> <command:noun>WslDistribution</command:noun> <maml:description> <maml:para>Imports a WSL distribution from a gzipped tarball or VHD file.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `Import-WslDistribution` cmdlet imports a WSL distribution that was previously exported to a gzipped tarball or VHD file, for example using the `Export-WslDistribution` cmdlet.</maml:para> <maml:para>If you do not specify a distribution name, the name is derived from the input file name. For example, a file named "Ubuntu.tar.gz" would be imported to a distribution named "Ubuntu".</maml:para> <maml:para>A directory with the name of the distribution is created as a child of the path specified using the Destination parameter, unless the RawDestination parameter is used. This allows multiple distributions to be imported using a single command.</maml:para> <maml:para>This cmdlet can be used to import distributions to a new location, or with VHD files it can also register them using the VHD file in the supplied location using the InPlace parameter.</maml:para> <maml:para>This cmdlet wraps the functionality of `wsl.exe --import`.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Import-WslDistribution</maml:name> <command:parameter required="true" variableLength="true" globbing="true" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to a `.tar.gz` or `.vhdx` file to import. Wildcard characters are permitted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Destination</maml:name> <maml:description> <maml:para>Specifies the destination directory where the file system for the imported distribution will be stored.</maml:para> <maml:para>Unless the RawDestination parameter is used, the name of the distribution will be appended to this path as a subdirectory.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of the imported WSL distribution.</maml:para> <maml:para>If you specify an explicit distribution name, you cannot import multiple distributions with a single command.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>Version</maml:name> <maml:description> <maml:para>Specifies the distribution version to use for the imported distribution, either 1 or 2.</maml:para> <maml:para>If omitted, the currently configured default distribution version is used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>0</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="fmt"> <maml:name>Format</maml:name> <maml:description> <maml:para>Specifies the format of the file to import, which can be either a gzipped tarball or a VHD. `Auto` determines the format based on the file extension; `Tar` indicates the file is a gzipped tarball; and `Vhd` indicates the file is a Virtual Hard Disk.</maml:para> <maml:para>When using `Auto`, all files are assumed to be gzipped tarballs, unless their name ends in `.vhdx`.</maml:para> <maml:para>Importing VHDs requires at least WSL version 0.58.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslExportFormat</command:parameterValue> <dev:type> <maml:name>WslExportFormat</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="rd"> <maml:name>RawDestination</maml:name> <maml:description> <maml:para>Specifies that the Destination path should be used as is, without appending the distribution name to it.</maml:para> <maml:para>If RawDestination is specified, you cannot import multiple distributions with one command.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Import-WslDistribution</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Destination</maml:name> <maml:description> <maml:para>Specifies the destination directory where the file system for the imported distribution will be stored.</maml:para> <maml:para>Unless the RawDestination parameter is used, the name of the distribution will be appended to this path as a subdirectory.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of the imported WSL distribution.</maml:para> <maml:para>If you specify an explicit distribution name, you cannot import multiple distributions with a single command.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>Version</maml:name> <maml:description> <maml:para>Specifies the distribution version to use for the imported distribution, either 1 or 2.</maml:para> <maml:para>If omitted, the currently configured default distribution version is used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>0</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="fmt"> <maml:name>Format</maml:name> <maml:description> <maml:para>Specifies the format of the file to import, which can be either a gzipped tarball or a VHD. `Auto` determines the format based on the file extension; `Tar` indicates the file is a gzipped tarball; and `Vhd` indicates the file is a Virtual Hard Disk.</maml:para> <maml:para>When using `Auto`, all files are assumed to be gzipped tarballs, unless their name ends in `.vhdx`.</maml:para> <maml:para>Importing VHDs requires at least WSL version 0.58.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslExportFormat</command:parameterValue> <dev:type> <maml:name>WslExportFormat</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="PSPath, LP"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to a `.tar.gz` or `.vhdx` file to import. The value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="rd"> <maml:name>RawDestination</maml:name> <maml:description> <maml:para>Specifies that the Destination path should be used as is, without appending the distribution name to it.</maml:para> <maml:para>If RawDestination is specified, you cannot import multiple distributions with one command.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Import-WslDistribution</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of the imported WSL distribution.</maml:para> <maml:para>If you specify an explicit distribution name, you cannot import multiple distributions with a single command.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="ip"> <maml:name>InPlace</maml:name> <maml:description> <maml:para>Specifies that the new distribution should use the input file in its current location, without copying it. The input must be a `.vhdx` file when importing in place.</maml:para> <maml:para>This parameter requires at least WSL version 0.58.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="PSPath, LP"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to a `.tar.gz` or `.vhdx` file to import. The value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Import-WslDistribution</maml:name> <command:parameter required="true" variableLength="true" globbing="true" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to a `.tar.gz` or `.vhdx` file to import. Wildcard characters are permitted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of the imported WSL distribution.</maml:para> <maml:para>If you specify an explicit distribution name, you cannot import multiple distributions with a single command.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="ip"> <maml:name>InPlace</maml:name> <maml:description> <maml:para>Specifies that the new distribution should use the input file in its current location, without copying it. The input must be a `.vhdx` file when importing in place.</maml:para> <maml:para>This parameter requires at least WSL version 0.58.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Destination</maml:name> <maml:description> <maml:para>Specifies the destination directory where the file system for the imported distribution will be stored.</maml:para> <maml:para>Unless the RawDestination parameter is used, the name of the distribution will be appended to this path as a subdirectory.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="fmt"> <maml:name>Format</maml:name> <maml:description> <maml:para>Specifies the format of the file to import, which can be either a gzipped tarball or a VHD. `Auto` determines the format based on the file extension; `Tar` indicates the file is a gzipped tarball; and `Vhd` indicates the file is a Virtual Hard Disk.</maml:para> <maml:para>When using `Auto`, all files are assumed to be gzipped tarballs, unless their name ends in `.vhdx`.</maml:para> <maml:para>Importing VHDs requires at least WSL version 0.58.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslExportFormat</command:parameterValue> <dev:type> <maml:name>WslExportFormat</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="ip"> <maml:name>InPlace</maml:name> <maml:description> <maml:para>Specifies that the new distribution should use the input file in its current location, without copying it. The input must be a `.vhdx` file when importing in place.</maml:para> <maml:para>This parameter requires at least WSL version 0.58.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="PSPath, LP"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to a `.tar.gz` or `.vhdx` file to import. The value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of the imported WSL distribution.</maml:para> <maml:para>If you specify an explicit distribution name, you cannot import multiple distributions with a single command.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="true" pipelineInput="True (ByPropertyName, ByValue)" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>Specifies the path to a `.tar.gz` or `.vhdx` file to import. Wildcard characters are permitted.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="rd"> <maml:name>RawDestination</maml:name> <maml:description> <maml:para>Specifies that the Destination path should be used as is, without appending the distribution name to it.</maml:para> <maml:para>If RawDestination is specified, you cannot import multiple distributions with one command.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>Version</maml:name> <maml:description> <maml:para>Specifies the distribution version to use for the imported distribution, either 1 or 2.</maml:para> <maml:para>If omitted, the currently configured default distribution version is used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>0</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>You can pipe a string that contains a path to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>WslDistribution</maml:name> </dev:type> <maml:description> <maml:para>An object representing the imported distribution. See `Get-WslDistribution` for more information.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Import-WslDistribution D:\backup.tar.gz D:\wsl "Ubuntu" Name State Version Default ---- ----- ------- ------- Ubuntu Stopped 2 False</dev:code> <dev:remarks> <maml:para>This example imports the file named `D:\backup.tar.gz` as a distribution named "Ubuntu", whose filesystem will be stored in the directory `D:\wsl\Ubuntu`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Import-WslDistribution D:\backup.tar.gz D:\wsl\mydistro "Ubuntu" -RawDestination Name State Version Default ---- ----- ------- ------- Ubuntu Stopped 2 False</dev:code> <dev:remarks> <maml:para>This example imports the file named `D:\backup.tar.gz` as a distribution named "Ubuntu", whose file system will be stored in the directory `D:\wsl\mydistro`. The name of the distribution is not appended to this path because the RawDestination parameter was used.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Import-WslDistribution D:\backup\*.tar.gz D:\wsl Name State Version Default ---- ----- ------- ------- Alpine Stopped 2 False Debian Stopped 2 False Ubuntu Stopped 2 False</dev:code> <dev:remarks> <maml:para>This example imports all `.tar.gz` files from `D:\backup`, using the base name of each file as the name of the distribution. Each distribution will be stored in a separate subdirectory of `D:\wsl`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title> <dev:code>Import-WslDistribution D:\backup\*.vhdx D:\wsl Name State Version Default ---- ----- ------- ------- Alpine Stopped 2 False Debian Stopped 2 False Ubuntu Stopped 2 False</dev:code> <dev:remarks> <maml:para>This example imports all `.vhdx` files from `D:\backup`, using the base name of each file as the name of the distribution. Each VHD file will be copied to a separate subdirectory of `D:\wsl`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 5 --------------------------</maml:title> <dev:code>Import-WslDistribution -InPlace D:\wsl\Ubuntu.vhdx | Set-WslDistribution -Default</dev:code> <dev:remarks> <maml:para>This example imports the file named `D:\wsl\Ubuntu.vhdx` as a distribution named "Ubuntu", using the file at its present location. It then makes the new distribution the default distribution.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 6 --------------------------</maml:title> <dev:code>Get-Item D:\backup\*.tar.gz -Exclude "Ubuntu*" | Import-WslDistribution -Destination D:\wsl -Version 1 Name State Version Default ---- ----- ------- ------- Alpine Stopped 1 False Debian Stopped 1 False</dev:code> <dev:remarks> <maml:para>This example imports all `.tar.gz` files, except those whose names start with Ubuntu, as WSL1 distributions stored in subdirectories of `D:\wsl`.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Import-WslDistribution.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-WslDistribution</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Export-WslDistribution</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Invoke-WslCommand</command:name> <command:verb>Invoke</command:verb> <command:noun>WslCommand</command:noun> <maml:description> <maml:para>Runs a command in a WSL distribution.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `Invoke-WslCommand` cmdlet executes a command in a WSL distribution, returning the output of the command as a string. The distribution to run the command in can be specified by name, or piped in from the `Get-WslDistribution` cmdlet. If no distribution is specified, the command is executed in the default distribution.</maml:para> <maml:para>This cmdlet will throw an exception if executing `wsl.exe` failed (e.g. if there is no distribution with the specified name), or if the command exited with an non-zero exit code.</maml:para> <maml:para>The command to execute can be specified in two ways. The default is using the Command parameter, where you provide the command in a single string, that will be passed to `/bin/sh -c` to execute it.</maml:para> <maml:para>Alternatively, you can use the RawCommand parameter to use all remaining parameters which do not match a known parameter for this cmdlet as the command. You can use the `--` separator to pass everything after to the WSL command. In this case, the command will be interpreted by the default shell configured in the distribution, rather than `/bin/sh`. See the examples for an example of this usage.</maml:para> <maml:para>This cmdlet wraps the functionality of `wsl.exe <command>`. If using the Graphical parameter, it instead wraps `wslg.exe <command>`.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-WslCommand</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Command</maml:name> <maml:description> <maml:para>Specifies the command to run, as a string that will be used with `/bin/sh -c`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>User</maml:name> <maml:description> <maml:para>Specifies the Linux user to run the command as. If omitted, the default user for the distribution is used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Graphical</maml:name> <maml:description> <maml:para>Specifies that the command should be executed using WSLg. Using this option prevents blocking the terminal while running GUI applications.</maml:para> <maml:para>This parameter requires at least WSL version 0.47.1.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="st"> <maml:name>ShellType</maml:name> <maml:description> <maml:para>Specifies the shell type to use for the command, either `Standard`, `Login`, or `None`. Note that if you are not using the RawCommand parameter, the command is still executed using `/bin/sh` on top of the selected shell type.</maml:para> <maml:para>This parameter requires at least WSL version 0.64.1.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>System</maml:name> <maml:description> <maml:para>Specifies that the command should be executed in the system distribution.</maml:para> <maml:para>This parameter requires at least WSL version 0.47.1.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wd, cd"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>Specifies the working directory to use for the command. Use `~` for the Linux user's home path. If the path starts with a `/` character, it will be interpreted as an absolute Linux path. Otherwise, the value must be a Windows path.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="true" pipelineInput="True (ByValue)" position="named" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of a distribution to run the command in.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Invoke-WslCommand</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Command</maml:name> <maml:description> <maml:para>Specifies the command to run, as a string that will be used with `/bin/sh -c`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>User</maml:name> <maml:description> <maml:para>Specifies the Linux user to run the command as. If omitted, the default user for the distribution is used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Distribution</maml:name> <maml:description> <maml:para>Specifies the distribution to run the command in.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslDistribution[]</command:parameterValue> <dev:type> <maml:name>WslDistribution[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Graphical</maml:name> <maml:description> <maml:para>Specifies that the command should be executed using WSLg. Using this option prevents blocking the terminal while running GUI applications.</maml:para> <maml:para>This parameter requires at least WSL version 0.47.1.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="st"> <maml:name>ShellType</maml:name> <maml:description> <maml:para>Specifies the shell type to use for the command, either `Standard`, `Login`, or `None`. Note that if you are not using the RawCommand parameter, the command is still executed using `/bin/sh` on top of the selected shell type.</maml:para> <maml:para>This parameter requires at least WSL version 0.64.1.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>System</maml:name> <maml:description> <maml:para>Specifies that the command should be executed in the system distribution.</maml:para> <maml:para>This parameter requires at least WSL version 0.47.1.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wd, cd"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>Specifies the working directory to use for the command. Use `~` for the Linux user's home path. If the path starts with a `/` character, it will be interpreted as an absolute Linux path. Otherwise, the value must be a Windows path.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Invoke-WslCommand</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>User</maml:name> <maml:description> <maml:para>Specifies the Linux user to run the command as. If omitted, the default user for the distribution is used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Distribution</maml:name> <maml:description> <maml:para>Specifies the distribution to run the command in.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslDistribution[]</command:parameterValue> <dev:type> <maml:name>WslDistribution[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Graphical</maml:name> <maml:description> <maml:para>Specifies that the command should be executed using WSLg. Using this option prevents blocking the terminal while running GUI applications.</maml:para> <maml:para>This parameter requires at least WSL version 0.47.1.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RawCommand</maml:name> <maml:description> <maml:para>Specifies that all remaining unrecognized parameters to this cmdlet are used as the command to run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Remaining</maml:name> <maml:description> <maml:para>Collects the remaining arguments for when the RawCommand parameter is supplied.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="st"> <maml:name>ShellType</maml:name> <maml:description> <maml:para>Specifies the shell type to use for the command, either `Standard`, `Login`, or `None`. Note that if you are not using the RawCommand parameter, the command is still executed using `/bin/sh` on top of the selected shell type.</maml:para> <maml:para>This parameter requires at least WSL version 0.64.1.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>System</maml:name> <maml:description> <maml:para>Specifies that the command should be executed in the system distribution.</maml:para> <maml:para>This parameter requires at least WSL version 0.47.1.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wd, cd"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>Specifies the working directory to use for the command. Use `~` for the Linux user's home path. If the path starts with a `/` character, it will be interpreted as an absolute Linux path. Otherwise, the value must be a Windows path.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Invoke-WslCommand</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>User</maml:name> <maml:description> <maml:para>Specifies the Linux user to run the command as. If omitted, the default user for the distribution is used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Graphical</maml:name> <maml:description> <maml:para>Specifies that the command should be executed using WSLg. Using this option prevents blocking the terminal while running GUI applications.</maml:para> <maml:para>This parameter requires at least WSL version 0.47.1.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RawCommand</maml:name> <maml:description> <maml:para>Specifies that all remaining unrecognized parameters to this cmdlet are used as the command to run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Remaining</maml:name> <maml:description> <maml:para>Collects the remaining arguments for when the RawCommand parameter is supplied.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="st"> <maml:name>ShellType</maml:name> <maml:description> <maml:para>Specifies the shell type to use for the command, either `Standard`, `Login`, or `None`. Note that if you are not using the RawCommand parameter, the command is still executed using `/bin/sh` on top of the selected shell type.</maml:para> <maml:para>This parameter requires at least WSL version 0.64.1.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>System</maml:name> <maml:description> <maml:para>Specifies that the command should be executed in the system distribution.</maml:para> <maml:para>This parameter requires at least WSL version 0.47.1.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wd, cd"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>Specifies the working directory to use for the command. Use `~` for the Linux user's home path. If the path starts with a `/` character, it will be interpreted as an absolute Linux path. Otherwise, the value must be a Windows path.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="true" pipelineInput="True (ByValue)" position="named" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of a distribution to run the command in.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Command</maml:name> <maml:description> <maml:para>Specifies the command to run, as a string that will be used with `/bin/sh -c`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Distribution</maml:name> <maml:description> <maml:para>Specifies the distribution to run the command in.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslDistribution[]</command:parameterValue> <dev:type> <maml:name>WslDistribution[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Graphical</maml:name> <maml:description> <maml:para>Specifies that the command should be executed using WSLg. Using this option prevents blocking the terminal while running GUI applications.</maml:para> <maml:para>This parameter requires at least WSL version 0.47.1.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RawCommand</maml:name> <maml:description> <maml:para>Specifies that all remaining unrecognized parameters to this cmdlet are used as the command to run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Remaining</maml:name> <maml:description> <maml:para>Collects the remaining arguments for when the RawCommand parameter is supplied.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="st"> <maml:name>ShellType</maml:name> <maml:description> <maml:para>Specifies the shell type to use for the command, either `Standard`, `Login`, or `None`. Note that if you are not using the RawCommand parameter, the command is still executed using `/bin/sh` on top of the selected shell type.</maml:para> <maml:para>This parameter requires at least WSL version 0.64.1.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>System</maml:name> <maml:description> <maml:para>Specifies that the command should be executed in the system distribution.</maml:para> <maml:para>This parameter requires at least WSL version 0.47.1.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>User</maml:name> <maml:description> <maml:para>Specifies the Linux user to run the command as. If omitted, the default user for the distribution is used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wd, cd"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>Specifies the working directory to use for the command. Use `~` for the Linux user's home path. If the path starts with a `/` character, it will be interpreted as an absolute Linux path. Otherwise, the value must be a Windows path.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="true" pipelineInput="True (ByValue)" position="named" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of a distribution to run the command in.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>WslDistribution</maml:name> </dev:type> <maml:description> <maml:para>You can pipe an object retrieved by `Get-WslDistribution` to this cmdlet.</maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>You can pipe a distribution name to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>This cmdlet returns the output of the command, as text. If the Graphical parameter is used, no output will be returned, and the command finishes while the application may still be executing.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Invoke-WslCommand "ls /etc"</dev:code> <dev:remarks> <maml:para>This example runs a command in the default distribution.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Invoke-WslCommand "whoami" -DistributionName "Ubuntu*" -User "root"</dev:code> <dev:remarks> <maml:para>This example runs a command in all distributions whose name starts with "Ubuntu", as the "root" Linux user.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Get-WslDistribution -Version 2 | Invoke-WslCommand 'echo $(whoami) in $WSL_DISTRO_NAME'</dev:code> <dev:remarks> <maml:para>This example runs a command in all WSL2 distributions. Single quotes are used to prevent the dollar sign from being interpreted by PowerShell without needing to escape them, instead passing them to the Linux shell.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title> <dev:code>Invoke-WslCommand -RawCommand echo Hello, $`(whoami`)</dev:code> <dev:remarks> <maml:para>This example uses the RawCommand parameter, so all unrecognized remaining parameters will form the command, without needing to quote it. Characters that would be interpreted by PowerShell need to be escaped with a backtick.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 5 --------------------------</maml:title> <dev:code>Invoke-WslCommand -RawCommand -- ls -u</dev:code> <dev:remarks> <maml:para>This example uses the RawCommand parameter, and uses the `--` separator to use everything after it as part of the Linux command, even if it is a valid parameter for `Invoke-WslCommand`. This prevents `-u` from being interpreted as an alias for the User argument.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Invoke-WslCommand.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-WslDistribution</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Enter-WslDistribution</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Remove-WslDistribution</command:name> <command:verb>Remove</command:verb> <command:noun>WslDistribution</command:noun> <maml:description> <maml:para>Unregisters a WSL distribution.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `Remove-WslDistribution` cmdlet unregisters a WSL distribution. The distribution to remove can be specified by name, or piped in from the `Get-WslDistribution` cmdlet.</maml:para> <maml:para>Removing a WSL distribution deletes its file system and all the data it contained.</maml:para> <maml:para>This cmdlet wraps the functionality of `wsl.exe --unregister`.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Remove-WslDistribution</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Distribution</maml:name> <maml:description> <maml:para>Specifies the distribution to be removed.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslDistribution[]</command:parameterValue> <dev:type> <maml:name>WslDistribution[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Remove-WslDistribution</maml:name> <command:parameter required="true" variableLength="true" globbing="true" pipelineInput="True (ByValue)" position="1" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of a distribution to be removed.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Distribution</maml:name> <maml:description> <maml:para>Specifies the distribution to be removed.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslDistribution[]</command:parameterValue> <dev:type> <maml:name>WslDistribution[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="true" pipelineInput="True (ByValue)" position="1" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of a distribution to be removed.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>WslDistribution</maml:name> </dev:type> <maml:description> <maml:para>You can pipe an object retrieved by `Get-WslDistribution` to this cmdlet.</maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>You can pipe a distribution name to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues /> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Remove-WslDistribution Ubuntu</dev:code> <dev:remarks> <maml:para>This example unregisters the distribution named "Ubuntu".</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Remove-WslDistribution "Ubuntu*"</dev:code> <dev:remarks> <maml:para>This example unregisters all distributions whose name starts with "Ubuntu".</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Get-WslDistribution -Version 1 | Remove-WslDistribution</dev:code> <dev:remarks> <maml:para>This example unregisters all WSL1 distributions.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 4 --------------------------</maml:title> <dev:code>Get-WslDistribution | Where-Object { $_.Name -ine "Ubuntu" } | Remove-WslDistribution</dev:code> <dev:remarks> <maml:para>This example unregisters all distributions except the one named "Ubuntu".</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Remove-WslDistribution.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-WslDistribution</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Set-WslDistribution</command:name> <command:verb>Set</command:verb> <command:noun>WslDistribution</command:noun> <maml:description> <maml:para>Changes the settings of a WSL distribution.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `Set-WslDistribution` cmdlet changes the settings of a WSL distribution. The distribution can be specified by name, or piped in from the `Get-WslDistribution` cmdlet.</maml:para> <maml:para>This cmdlet wraps the functionality of `wsl.exe --set-default` and `wsl.exe --set-version`.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Set-WslDistribution</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Default</maml:name> <maml:description> <maml:para>Specifies that the distribution should be made the default distribution. If the input specifies multiple distributions, the last one processed will be the default after the command finishes.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Distribution</maml:name> <maml:description> <maml:para>Specifies the distribution whose settings to change.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslDistribution[]</command:parameterValue> <dev:type> <maml:name>WslDistribution[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Passthru</maml:name> <maml:description> <maml:para>Specifies that a WslDistribution object is to be passed through to the pipeline representing the distribution whose settings were changed.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Version</maml:name> <maml:description> <maml:para>Specifies the WSL distribution version to convert the distribution to, either 1 or 2. Converting a distribution may take several minutes.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>0</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Set-WslDistribution</maml:name> <command:parameter required="true" variableLength="true" globbing="true" pipelineInput="True (ByValue)" position="1" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of a distribution whose settings to change.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Default</maml:name> <maml:description> <maml:para>Specifies that the distribution should be made the default distribution. If the input specifies multiple distributions, the last one processed will be the default after the command finishes.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Passthru</maml:name> <maml:description> <maml:para>Specifies that a WslDistribution object is to be passed through to the pipeline representing the distribution whose settings were changed.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Version</maml:name> <maml:description> <maml:para>Specifies the WSL distribution version to convert the distribution to, either 1 or 2. Converting a distribution may take several minutes.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>0</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Default</maml:name> <maml:description> <maml:para>Specifies that the distribution should be made the default distribution. If the input specifies multiple distributions, the last one processed will be the default after the command finishes.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Distribution</maml:name> <maml:description> <maml:para>Specifies the distribution whose settings to change.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslDistribution[]</command:parameterValue> <dev:type> <maml:name>WslDistribution[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="true" pipelineInput="True (ByValue)" position="1" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of a distribution whose settings to change.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Passthru</maml:name> <maml:description> <maml:para>Specifies that a WslDistribution object is to be passed through to the pipeline representing the distribution whose settings were changed.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Version</maml:name> <maml:description> <maml:para>Specifies the WSL distribution version to convert the distribution to, either 1 or 2. Converting a distribution may take several minutes.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>0</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>WslDistribution</maml:name> </dev:type> <maml:description> <maml:para>You can pipe an object retrieved by `Get-WslDistribution` to this cmdlet.</maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>You can pipe a distribution name to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None by default; WslDistribution if PassThru is specified</maml:name> </dev:type> <maml:description> <maml:para>See `Get-WslDistribution` for more information.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Set-WslDistribution Ubuntu -Default</dev:code> <dev:remarks> <maml:para>This example makes the distribution named "Ubuntu" the default.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Get-WslDistribution -Version 1 | Set-WslDistribution -Version 2 -Passthru Name State Version Default ---- ----- ------- ------- Ubuntu-18.04 Running 2 False Debian Stopped 2 False</dev:code> <dev:remarks> <maml:para>This example converts all version 1 distributions to version 2. It uses the Passthru parameter to return the WslDistribution objects for the affected distributions.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Set-WslDistribution.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-WslDistribution</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Stop-Wsl</command:name> <command:verb>Stop</command:verb> <command:noun>Wsl</command:noun> <maml:description> <maml:para>Terminates all WSL distributions, and shuts down the WSL2 lightweight utility VM.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `Stop-Wsl` cmdlet terminates all WSL distributions, and shuts down the WSL2 lightweight utility VM.</maml:para> <maml:para>This cmdlet wraps the functionality of `wsl.exe --shutdown`.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Stop-Wsl</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues /> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Stop-Wsl</dev:code> <dev:remarks> <maml:para>This example terminates all WSL distributions, and shuts down the WSL2 lightweight utility VM.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Stop-Wsl.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Stop-WslDistribution</command:name> <command:verb>Stop</command:verb> <command:noun>WslDistribution</command:noun> <maml:description> <maml:para>Terminates a WSL distribution.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `Stop-WslDistribution` cmdlet terminates a WSL distribution. The distribution to stop can be specified by name, or piped in from the `Get-WslDistribution` cmdlet.</maml:para> <maml:para>This cmdlet wraps the functionality of `wsl.exe --terminate`.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Stop-WslDistribution</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Distribution</maml:name> <maml:description> <maml:para>Specifies the distribution to be terminated.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslDistribution[]</command:parameterValue> <dev:type> <maml:name>WslDistribution[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Passthru</maml:name> <maml:description> <maml:para>Specifies that a WslDistribution object is to be passed through to the pipeline representing the distribution to be shutdown.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Stop-WslDistribution</maml:name> <command:parameter required="true" variableLength="true" globbing="true" pipelineInput="True (ByValue)" position="1" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of a distribution to be terminated.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Passthru</maml:name> <maml:description> <maml:para>Specifies that a WslDistribution object is to be passed through to the pipeline representing the distribution to be shutdown.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>Distribution</maml:name> <maml:description> <maml:para>Specifies the distribution to be terminated.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WslDistribution[]</command:parameterValue> <dev:type> <maml:name>WslDistribution[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="true" pipelineInput="True (ByValue)" position="1" aliases="DistributionName"> <maml:name>Name</maml:name> <maml:description> <maml:para>Specifies the name of a distribution to be terminated.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Passthru</maml:name> <maml:description> <maml:para>Specifies that a WslDistribution object is to be passed through to the pipeline representing the distribution to be shutdown.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>WslDistribution</maml:name> </dev:type> <maml:description> <maml:para>You can pipe an object retrieved by `Get-WslDistribution` to this cmdlet.</maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>You can pipe a distribution name to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None by default; WslDistribution if PassThru is specified</maml:name> </dev:type> <maml:description> <maml:para>See `Get-WslDistribution` for more information.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Stop-WslDistribution "Ubuntu"</dev:code> <dev:remarks> <maml:para>This example stops the distribution named "Ubuntu".</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Stop-WslDistribution "Ubuntu*"</dev:code> <dev:remarks> <maml:para>This example terminates all distributions whose name starts with "Ubuntu".</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>Get-WslDistribution -Version 2 | Stop-WslDistribution -Passthru Name State Version Default ---- ----- ------- ------- Ubuntu Stopped 2 True Alpine Stopped 2 False</dev:code> <dev:remarks> <maml:para>This example terminates all WSL2 distributions. It uses the Passthru parameter to return the WslDistribution objects for the affected distributions.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/SvenGroot/WslManagementPS/blob/main/docs/Stop-WslDistribution.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Get-WslDistribution</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |