How to install Multipass

Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.

This guide explains how to install and manage Multipass on your system.

Select the tab corresponding to your operating system (e.g. Linux) to display the relevant content in each section. Your decision will stick until you select another OS from the drop-down menu.

Check prerequisites

Multipass for Linux is published as a snap package, available on the Snap Store. Before you can use it, you need to install snapd. snapd is included in Ubuntu by default.

The default backend on macOS is qemu, wrapping Apple’s Hypervisor framework. You can use any Mac (M1, M2, or Intel based) with macOS 10.15 Catalina or later installed.

Hyper-V

Only Windows 10 Pro or Enterprise version 1803 (“April 2018 Update”) or later are currently supported, due to the necessary version of Hyper-V only being available on those versions.

VirtualBox

Multipass also supports using VirtualBox as a virtualization provider. You can download the latest version from the VirtualBox download page.

Install

To install Multipass, run the following command:

snap install multipass

For architectures other than amd64, you’ll need the beta channel at the moment.

You can also use the edge channel to get the latest development build:

snap install multipass --edge

Make sure you’re part of the group that Multipass gives write access to its socket (sudo in this case, but it may also be adm or admin, depending on your distribution).

  1. Run this command to check which group is used by the Multipass socket:

    ls -l /var/snap/multipass/common/multipass_socket
    

    The output will be similar to the following:

    srw-rw---- 1 root sudo 0 Dec 19 09:47 /var/snap/multipass/common/multipass_socket
    
  2. Run the groups command to make sure you are a member of that group (in our example, “sudo”):

    groups | grep sudo
    

    The output will be similar to the following:

    adm cdrom sudo dip plugdev lpadmin
    

You can view more information on the snap package using the snap info command:

snap info multipass

For example:

name:      multipass
summary:   Instant Ubuntu VMs
publisher: Canonical✓
store-url: https://snapcraft.io/multipass
contact:   https://github.com/CanonicalLtd/multipass/issues/new
license:   GPL-3.0
description: |
  Multipass is a tool to launch and manage VMs on Windows, Mac and Linux that simulates a cloud
  environment with support for cloud-init. Get Ubuntu on-demand with clean integration to your IDE
  and version control on your native platform.
  ...
commands:
  - multipass.gui
  - multipass
services:
  multipass.multipassd: simple, enabled, active
snap-id:      mA11087v6dR3IEcQLgICQVjuvhUUBUKM
tracking:     latest/candidate
refresh-date: 5 days ago, at 10:13 CEST
channels:
  latest/stable:    1.3.0                 2020-06-17 (2205) 228MB -
  latest/candidate: 1.3.0                 2020-06-17 (2205) 228MB -
  latest/beta:      1.3.0-dev.17+gf89e1db 2020-04-28 (2019) 214MB -
  latest/edge:      1.4.0-dev.83+g149f10a 2020-06-17 (2216) 228MB -
installed:          1.3.0                            (2205) 228MB -

To install Multipass on macOS, you have two options:

Upgrade and uninstall options depend on this choice as well.

Install via installer package

You will need an account with administrator privileges to complete the installation.

Download the latest installer from our download page. You can also get pre-release versions from the GitHub releases page, look for the .pkg package.

Run the downloaded installer and follow the guided procedure.

Multipass installer on macOS

Install using brew

If you haven’t already, install Brew. Then, run the following command:

brew install multipass

If you want Tab completion on the command line, install bash-completion@2 from brew and follow these instructions on updating your .bashrc file.

You will need either Hyper-V enabled (only Windows 10 Professional or Enterprise), or VirtualBox installed. See Check prerequisites.

Download the latest installer from our download page. You can also get pre-release versions from the GitHub releases page, look for the .exe file.

Run the downloaded installer and follow the guided procedure. You will need to allow the installer to gain Administrator privileges.

Run

You’ve installed Multipass. Time to run your first commands! Use multipass version to check your version or multipass launch to create your first instance.

You’ve installed Multipass. Time to run your first commands! Use multipass version to check your version or multipass launch to create your first instance.

See also: How to set up the driver, How to use a different terminal from the system icon

You’ve installed Multipass. Time to run your first commands! Launch a Command Prompt (cmd.exe) or PowerShell as a regular user. Use multipass version to check your version or multipass launch to create your first instance.

Multipass defaults to using Hyper-V as its virtualization provider. If you’d like to use VirtualBox, you can do so using the following command:

multipass set local.driver=virtualbox

See also: How to set up the driver.

Upgrade

As the installation happened via snap, you don’t need to worry about upgrading—it will be done automatically.

The upgrade procedure depends on your installation method:

Upgrade via installer package

You will need an account with administrator privileges to complete the upgrade.

To upgrade, download the latest installer from our download page. You can also get pre-release versions from the GitHub releases page, look for the .pkg package.

Run the downloaded installer and follow the guided procedure.

Any existing instances will be preserved.

Upgrade using brew

Run the command:

brew upgrade multipass

To upgrade, download the latest installer and run it. You can also get pre-release versions from the GitHub releases page, look for the .exe package.

You will be asked to uninstall the old version, and then whether to remove all data when uninstalling. If you want to keep your existing instances, answer “No” (default).

Uninstall

To uninstall Multipass, run the following command:

snap remove multipass

The uninstall procedure depends on your installation method:

Uninstall via installer package

To uninstall Multipass, run the script:

sudo sh "/Library/Application Support/com.canonical.multipass/uninstall.sh"

Uninstall using brew

To uninstall while keeping your VMs and data, use the following command:

brew uninstall multipass

Caveats:

Although Brew supports the --zap option to remove all data, it does not allow Multipass to remove all VMs and data properly. The Multipass daemon needs to be alive and running to unregister VMs from certain backends (e.g. VirtualBox). However, Brew executes the zap procedure strictly after the uninstall step. By then, the Multipass daemon is no longer available.

This GitHub issue provides more information.

The workaround is to remove VMs manually before uninstalling, using the following commands:

multipass delete --purge --all
brew uninstall --zap multipass

The --zap option destroys all other data, too

Uninstall Multipass as you would any other program, following the usual procedure.


Let us know how this worked for you and what you’d like to see next!


Contributors: @saviq , @townsend , @sowasred2012 , @ya-bo-ng , @shuuji3 , @henryschreineriii , @sven , @nick3499 , @undefynd , @sparkiegeek , @nottrobin , @tmihoc , @nhart , @luisp , @sharder996 , @aaryan-porwal , @andreitoterman , @ricab , @gzanchi , @bagustris

Last updated 11 days ago. Help improve this document in the forum.