How to install Multipass on macOS

This page is no longer maintained. Please refer to How to install Multipass.

See also: How to use VirtualBox in Multipass on macOS, How to use a different terminal on macOS

Contents:

Check prerequisites

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.

Install, upgrade, uninstall

To install Multipass on macOS, you have two options: the installer package or brew. Upgrading and uninstallation options depend on this choice as well.

Using the installer package

Download the latest installer from here. You can also get pre-release versions from our GitHub releases page - it’s the .pkg package.

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

Activate the downloaded installer and it will guide you through the necessary steps. You will need an account with administrator privileges to complete the installation.

Multipass installer on macOS

To uninstall, run the script:

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

Using brew

If you don’t have it already, install Brew. Then, to install Multipass simply execute:

$ brew install multipass

To uninstall while keeping your VMs and data, you can use:

$ brew uninstall multipass

Caveats:
Although Brew supports the --zap option to remove all data, it does not allow Multipass to remove all the 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 issue report has more information. The workaround is to remove VMs manually before uninstalling:

  1. multipass delete --purge --all
  2. brew uninstall --zap multipass # to destroy all other data, too

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.

1 Like

How do you uninstall multipass on Mac OS?

If we have Homebrew, we can install/uninstall multipass with the following commands:

Install

$ brew cask install multipass
$ multipass version
multipass  0.8.0+mac
multipassd 0.8.0+mac

Uninstall

$ brew cask uninstall multipass
1 Like

Thanks @shuuji3 I’ve now incorporated that into the main post above.

1 Like

Thanks for improving the documentation!
It should help many developers. :slight_smile:

By the way, you’ve left off the “cask” part of the uninstall commands, so they don’t work, and give an “Error: Unknown command: zap” message, which isn’t very helpful. It’s brew cask uninstall multipass and brew cask zap multipass. Otherwise, thanks for the info!

1 Like

Hi @henryschreineriii sorry about that, thanks for noticing! Updated the post.

1 Like

Hi, many thanks for the tool and documentation.

Two things come to my mind:

  1. Could you provide information here (as on the Windows installation page) which prerequisites, especially virtualisation methods are used/available?

  2. With the 1.0 release of today, can you update the output of multipass version at this page?

Thanks

Hi @sven, I’ve now made the changes you mentioned. Thanks for prompting :).

1 Like

3 posts were split to a new topic: Minimum macOS version for Multipass?

If you did not use brew to install you can uninstall from macOS like this:

sudo sh “/Library/Application Support/com.canonical.multipass/uninstall.sh”

We have received an issue on the website about this content.

TLDR;
Homebrew sends GA events. Which can be disabled but the user needs to know-how. I would suggest adding a small comment with a link to docs to disable analytics.

Is there a way to install multipass from the source code on macOS?

The brew command you guys specify in the documentation is outdated.

to install run

brew install --cask multipass

Hi @apagiaro, we’re keeping some macOS and Windows parts closed-source for now, so no, we don’t currently provide a way to build or install from source on those platforms.

Hi @undefynd, thanks for point that out. I have just updated those commands.

I think the uninstall command to zap is

brew uninstall --zap --cask multipass

Doesn’t look it:

Error: invalid option: --zap

After installing with brew and adding my user to the admin group, I still need a sudo to use multipass, otherwise

$ multipass shell charm-dev-29                                                                                                                                                      
shell failed: The client is not authenticated with the Multipass service.
Please use 'multipass authenticate' before proceeding.

And authenticate doesn’t seem to work: the passphrase gets rejected:

$ sudo multipass authenticate
Password:
Please enter passphrase: 
authenticate failed: Passphrase is not set. Please `multipass set local.passphrase` with a trusted client.

What’s a trusted client?

Hey @sed-i, have a look at at these docs on security and how to authenticate. The daemon will only deal with clients/users that it trusts. On Linux, that’s a) the first user belonging to the sudo group (+ root) who connects (presumably the one who installed the application) and b) clients that were able to authenticate with multipass authenticate thereafter.

So, when an administrator who installs multipass wants to allow others, he or she needs to set a password and share it with allowed users, who then need to multipass authenticate with it. You probably connected as root the first time, so only root is trusted by multipassd.