Basic commands for MSL
msl takes wsl's arguments and prints the same messages, so commands from WSL instructions work with msl in place of wsl. Run these in a macOS terminal. For the full list of options, run msl --help.
Install
$ msl --install <Distribution Name>
Installs a Linux distribution and runs its first-run setup, which asks you to create a Linux user. Without a name, it installs the distribution marked as the default in msl --list --online. See Install MSL.
Options:
--name: the name to give the distribution.--location: the folder for its disk,ext4.img.--no-launch,-n: install it without running its first-run setup.--from-file <Path>: install from a local.wslimage.--vhd-size <Size>: the maximum size of its disk, for example64GB.
--web-download and --fixed-vhd are accepted and ignored; disks are always sparse.
List available Linux distributions
$ msl --list --online
Lists the distributions you can install: the arm64 images in Microsoft's WSL distribution list. Also msl -l -o.
List installed Linux distributions
$ msl --list --verbose
Lists your distributions, whether each is running or stopped, and its version, which is always 2. Also msl -l -v. --all includes distributions being installed or removed, --running lists only running ones, and --quiet (-q) prints only the names.
Set the version to 1 or 2
$ msl --set-version <Distribution Name> 2
Accepted for compatibility. Every MSL distribution is version 2; version 1 isn't available on macOS.
Set the default version
$ msl --set-default-version 2
Accepted for compatibility. Only version 2 is available.
Set the default Linux distribution
$ msl --set-default <Distribution Name>
Sets the distribution that msl runs when you don't name one. Also msl -s <Distribution Name>.
Start in your home directory
$ msl ~
Starts a shell in your Linux home directory. Without ~, msl starts in the macOS directory you ran it from, under /mnt/macos. --cd <Directory> starts in any Linux directory.
Run a specific Linux distribution
$ msl --distribution <Distribution Name> --user <User Name>
Runs a distribution as a given user. Also msl -d <Distribution Name> -u <User Name>. The user must exist in the distribution.
Run a command
$ msl ls -la # through the distribution's shell: globs, variables and pipes work
$ msl -e uname -m # without a shell; the exit code is passed through
$ msl --cd ~ -- make test # everything after -- is passed as it is
$ git log | msl -e wc -l # stdin and stdout are pipes in both directions
An interactive command gets a terminal, as in WSL, and window resizes and Ctrl-C reach the Linux process. --shell-type <standard|login|none> chooses how the shell runs the command.
Update MSL
$ msl --update
Installs the latest MSL release in place and keeps your distributions and settings. --pre-release installs a pre-release if there is one. See Update and uninstall MSL.
Check the status
$ msl --status
Shows the default distribution and the VM's settings: memory, processors, kernel, networking, nested virtualization, idle timeouts, the distributions' disks and their use on macOS, and whether the VM is running. It also lists ~/.mslconfig changes that apply after the next msl --shutdown.
Check the version
$ msl --version
Shows the MSL, kernel and macOS versions. Also msl -v.
Help
$ msl --help
Lists every command and option.
Run as a specific user
$ msl --user <User Name>
Runs the default distribution as another user, for example msl -u root. The user must exist in the distribution.
Change the default user for a distribution
$ msl --manage <Distribution Name> --set-default-user <User Name>
Sets the user that shells run as. The user must exist in the distribution. [user] default in the distribution's /etc/wsl.conf does the same; see Advanced settings configuration.
Shut down
$ msl --shutdown
Stops every running distribution and the VM, and flushes every distribution's disk to the SSD. Use it to apply changes to ~/.mslconfig. --force stops the VM even if an operation is in progress, which can lose data.
Terminate
$ msl --terminate <Distribution Name>
Stops one distribution. Also msl -t <Distribution Name>.
Identify IP addresses
All distributions share one network, so they have the same IP address. From inside a distribution:
hostname -Iprints the VM's IP address.host.internal, which MSL adds to each distribution's/etc/hosts, is the address of the Mac as seen from Linux.
You rarely need either: a server in a distribution is reachable at localhost on macOS. See Networking.
Export a distribution
$ msl --export <Distribution Name> <FileName>
Writes the distribution to a tar file, the format wsl --import takes. Use - as the file name for stdout. --format tar.gz or --format tar.xz compresses it. --vhd copies the distribution's disk instead, as a raw ext4 image; it stops the distribution first.
Import a distribution
$ msl --import <Distribution Name> <InstallLocation> <FileName>
Imports a tar file as a new distribution, with its disk in <InstallLocation>. Use - as the file name for stdin. --vhd imports a raw ext4 disk image instead, copied to <InstallLocation>/ext4.img. See Import any Linux distribution.
Import a distribution in place
$ msl --import-in-place <Distribution Name> <FileName>
Registers a raw ext4 disk image as a new distribution, using the file where it is. msl --unregister deletes it.
Unregister or uninstall a Linux distribution
$ msl --unregister <Distribution Name>
Removes the distribution and deletes its files, including its disk, ext4.img, as WSL deletes ext4.vhdx.
Everything in the distribution is deleted permanently, including your files in its home directories. Export it first if you might need it again.
Move, grow or compact a distribution's disk
$ msl --manage <Distribution Name> --move <Location>
$ msl --manage <Distribution Name> --resize 512GB
$ msl --manage <Distribution Name> --compact
--move stops the distribution and moves its disk to another folder. --resize grows the disk of a stopped distribution; it can't shrink. --compact returns space freed inside the disk to macOS. See Manage disk space.
Mount a disk
$ msl --mount <Disk>
Attaches a disk image to the VM and mounts it at /mnt/msl/<Name> in every distribution. --name, --type (-t), --options (-o), --partition and --bare work as in WSL, and --vhd is accepted. See Mount a disk.
Unmount disks
$ msl --unmount <Disk>
Unmounts and detaches a disk. Without a disk, it detaches all of them.
Commands only in MSL
JSON output
$ msl --list --verbose --json
--json prints JSON instead of text for --list, --list --online, --status and --version. See Use JSON output in scripts.
Set up VS Code
$ msl --manage-ide
Sets up the MSL extension in VS Code, VS Code Insiders, VSCodium or Cursor. --ide <vscode|vscode-insiders|vscode-oss|cursor|all> picks the IDE, and --install or --uninstall says what to do. See Get started with VS Code.
Debug shell
$ msl --debug-shell
Opens a root shell in the utility VM itself, outside every distribution, for diagnosing problems.
Uninstall MSL
$ msl --uninstall
Removes MSL and its VS Code setup, and keeps your distributions and settings.
Not available on macOS
These wsl options have no macOS equivalent: --system, --enable-wsl1, --inbox, and WSL 1. --set-sparse is accepted, and disks are always sparse.