Get started with Multipass - macOS

Multipass is a flexible, powerful tool that can be used for many purposes. In its simplest form, it can be used to quickly create and destroy Ubuntu VMs (instances) on any host machine. Used to a fuller extent, Multipass is a local mini-cloud on your laptop, allowing the testing and development of multi-instance or container-based cloud applications.

This tutorial will teach you how to create, customise and manage instances using Multipass. You will also learn how to apply Multipass in two common use cases.

Contents

Install Multipass

Multipass is available for Linux, macOs, or Windows. To install it on your OS of choice, please follow the instructions given here. This tutorial gives instructions for using Multipass on macOS.

Create and use a basic instance

From the application launcher, let’s start Multipass. In macOS, open the application launcher, type Multipass, and launch the application.

Once we’ve launched the application, we should see the Multipass tray icon in the upper right section of the screen:

Let’s click on the icon, then on “Open Shell”.

Clicking this button does many things in the background: it creates a new virtual machine (instance), named primary, with 1GB of RAM, 5GB of disk, and 1 CPU; installs the most recent Ubuntu LTS release on that instance; mounts our $HOME directory in the instance; and opens a shell to the instance, announced by the command prompt ubuntu@primary. You can see elements of this in the printout below.

Launched: primary                                                               
Mounted '/home/<user>' into 'primary:Home'                                       
Welcome to Ubuntu 22.04.1 LTS (GNU/Linux 5.15.0-57-generic x86_64)

 * Documentation:  https://help.ubuntu.com
 * Management:     https://landscape.canonical.com
 * Support:        https://ubuntu.com/advantage

  System information as of Thu Jan 26 21:15:05 UTC 2023

  System load:  0.72314453125     Processes:             105
  Usage of /:   29.8% of 4.67GB   Users logged in:       0
  Memory usage: 20%               IPv4 address for ens3: 192.168.64.5
  Swap usage:   0%


0 updates can be applied immediately.


The list of available updates is more than a week old.
To check for new updates run: sudo apt update

ubuntu@primary:~$

Let’s test it out! As we just learned, the previous step automatically mounted our $HOME directory in the instance. Let’s use this to share data with our instance. More concretely, let’s create a new folder in our $HOME directory called Multipass_Files:

As you can see, I’ve added a readme file in this shared folder. Let’s check for the folder and read the file from our new instance:

ubuntu@primary:~$ cd ./Home/Multipass_Files/
ubuntu@primary:~/Home/Multipass_Files$ cat README.md 
## Shared Folder

This folder could be a great place to keep files that need to be accessed by both your host machine and Ubuntu VM!

ubuntu@primary:~/Home/Multipass_Files$

Congratulations, you’ve got your first instance!

This instance is great for when we just need a quick Ubuntu VM, but let’s say we want a more customised instance. Multipass has us covered there too!

Optional Exercises

Exercise 1:
When you clicked on Open Shell just now, what happened in the background was the equivalent of the CLI commands multipass launch –name primary followed by multipass shell. Open a terminal and try multipass shell (if you didn’t follow the steps above, you will have to run the launch command first).

Exercise 2:
In Multipass, an instance with the name primary is privileged. For example, it is the default argument of multipass shell. In two terminal instances, check multipass shell primary and multipass shell. Both commands should give the same result.

Create a customised instance

Multipass has a great feature to help us get started creating customised instances. Let’s open a terminal and run the command multipass find. This shows us a list of all of the images we can launch through Multipass currently.

$ multipass find
Image                       Aliases           Version          Description
snapcraft:core18            18.04             20201111         Snapcraft builder for Core 18
snapcraft:core20            20.04             20210921         Snapcraft builder for Core 20
snapcraft:core22            22.04             20220426         Snapcraft builder for Core 22
snapcraft:devel                               20230126         Snapcraft builder for the devel series
core                        core16            20200818         Ubuntu Core 16
core18                                        20211124         Ubuntu Core 18
core20                                        20230119         Ubuntu Core 20
core22                                        20230119         Ubuntu Core 22
18.04                       bionic            20230112         Ubuntu 18.04 LTS
20.04                       focal             20230117         Ubuntu 20.04 LTS
22.04                       jammy,lts         20230107         Ubuntu 22.04 LTS
22.10                       kinetic           20230112         Ubuntu 22.10
daily:23.04                 devel,lunar       20230125         Ubuntu 23.04
appliance:adguard-home                        20200812         Ubuntu AdGuard Home Appliance
appliance:mosquitto                           20200812         Ubuntu Mosquitto Appliance
appliance:nextcloud                           20200812         Ubuntu Nextcloud Appliance
appliance:openhab                             20200812         Ubuntu openHAB Home Appliance
appliance:plexmediaserver                     20200812         Ubuntu Plex Media Server Appliance
anbox-cloud-appliance                         latest           Anbox Cloud Appliance
charm-dev                                     latest           A development and testing environment for charmers
docker                                        0.4              A Docker environment with Portainer and related tools
jellyfin                                      latest           Jellyfin is a Free Software Media System that puts you in control of managing and streaming your media.
minikube                                      latest           minikube is local Kubernetes

Let’s launch an instance running Ubuntu 22.10 (“Kinetic Kudu”) by typing the command multipass launch kinetic

Now we have an instance running which has been named randomly by Multipass, in my case it is called breezy-liger.

$ multipass launch kinetic
Launched: breezy-liger

We can check some basic info about our new instance by running the following:

multipass exec breezy-liger -- lsb_release -a

This tells Multipass to execute the command lsb_release -a on the “breezy-liger” instance.

$ multipass exec breezy-liger -- lsb_release -a
No LSB modules are available.
Distributor ID:	Ubuntu
Description:	Ubuntu 22.10
Release:		22.10
Codename:		kinetic

Perhaps after using this instance for a while, we decide what we really need is the latest LTS version of Ubuntu, with a more informative name and a little more memory and disk. We can delete the breezy-liger instance by running

multipass delete breezy-liger

Let’s now launch the type of instance we’re looking for by running this:

multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2

Manage instances

Now let’s confirm this new instance has the specs we’re looking for by running multipass info ltsInstance

$ multipass info ltsInstance                             
Name:           ltsInstance
State:          Running
IPv4:           192.168.64.3
Release:        Ubuntu 22.04.1 LTS
Image hash:     3100a27357a0 (Ubuntu 22.04 LTS)
CPU(s):         2
Load:           1.55 0.44 0.15
Disk usage:     1.4GiB out of 9.5GiB
Memory usage:   155.5MiB out of 1.9GiB
Mounts:         --

We’ve created and deleted quite a few instances now. Let’s run Multipass list to see what instances we currently have.

$ multipass list                                         
Name                    State             IPv4             Image
primary                 Running           192.168.64.5     Ubuntu 22.04 LTS
breezy-liger            Deleted           --               Not Available
ltsInstance             Running           192.168.64.3     Ubuntu 22.04 LTS

We have two instances currently running, the primary instance and our LTS machine with customised specs. Our breezy-liger instance is still listed, but its state is “Deleted”. We can recover this instance by running multipass recover breezy-liger , but for right now let’s delete the instance permanently by running multipass purge. Running multipass list again confirms the instance is now permanently deleted:

$ multipass list                                         
Name                    State             IPv4             Image
primary                 Running           192.168.64.5     Ubuntu 22.04 LTS
ltsInstance             Running           192.168.64.3     Ubuntu 22.04 LTS

We’ve now seen a few ways to create, customise, and delete an instance. Now let’s put those instances to work!

Put your instances to use

Run a simple web server

Let’s go back to that customised LTS instance we created. Take note of its IP address revealed by multipass list in the previous step, then run multipass shell ltsInstance to open a shell in the instance.

From the shell, we can now run:

sudo apt update

sudo apt install apache2

Now, let’s open a browser and type in the IP address of the instance into the address bar. We should now see the default Apache homepage.

Just like that, we’ve got a web server running in a Multipass instance!

We can use this web server locally for any kind of local development or testing we like. If however, we want to access this web server from the internet (e.g. from a different computer), we need an instance that is exposed to the external network.

Launch from a Blueprint to run Docker containers

Some environments require a lot of configuration and setup. Multipass Blueprints are instances with a deep level of customization. The Docker Blueprint, for example, is a pre-configured Docker environment with a Portainer container already running. We can launch an instance using the Docker Blueprint by running multipass launch docker --name docker-dev

Once that’s finished, let’s run multipass info docker-dev to note down the IP of the new instance.

$ multipass launch docker --name docker-dev
Launched: docker-dev
$ multipass info docker-dev
Name:           docker-dev
State:          Running
IPv4:           10.115.5.235
                172.17.0.1
Release:        Ubuntu 22.04.1 LTS
Image hash:     3100a27357a0 (Ubuntu 22.04 LTS)
CPU(s):         2
Load:           1.40 0.64 0.25
Disk usage:     2.5GiB out of 38.6GiB
Memory usage:   236.4MiB out of 3.8GiB
Mounts:         --

Let’s take the first IP address shown and paste it into our browser, then add a colon and the portainer default port, 9000, like this: 10.115.5.235:9000. This will take us to the Portainer login page, where we can set a username and password.

From there, let’s select a local docker environment.

From there, we can click into the newly created “local” docker endpoint, navigate to the app templates page, and select NGINX

From the Portainer dashboard, we can see the ports that nginx has available. We can navigate to the IP address of our instance followed by that port number to see that we indeed have nginx running in a docker container inside Multipass!

Next steps

Congratulations! You now have the skills you need to use Multipass proficiently. There’s more to learn about Multipass and its capabilities - check out our how-to guides for ideas and for help with your project. Our reference page contains definitions of key concepts, a complete CLI command reference, settings options and more.

Let us know what you’re able to get done with Multipass!

3 Likes

Hi Nathan,

Thank you for the tutorial, it is very helpful. The only thing is that when i followed it the docker VM that I installed with:
$ multipass launch docker --name docker-dev
had no docker and Portainer installed:

$ multipass info docker-dev
Name: docker-dev
State: Running
IPv4: 192.168.64.6
Release: Ubuntu 22.04.1 LTS
Image hash: f753d6f9cea8 (Ubuntu 22.04 LTS)
Load: 0.01 0.07 0.07
Disk usage: 1.6G out of 38.6G
Memory usage: 173.6M out of 3.8G
Mounts: –

$ multipass exec docker-dev docker
bash: line 1: docker: command not found

Hi kirhist,
Thanks for reaching out. I’m not sure why that is happening, but it could be that some part of the cloud-init initialization built into the blueprint is failing. I would try to delete and purge the instance (multipass delete docker-dev then multipass purge), then try the launch command again. If that doesn’t work would you mind filing a bug report here?

Thanks and good luck!

Hello very simple to use. Any tips how make the vm accessible from outside the Mac ? Can find dozen tips on linux be not on Mac or bsd. Highly appreciated.

Hi @etiquet, if you are using either the qemu or the virtualbox backends, you can bridge your instance to a network interface on your host.

You just have to run multipass networks, choose a network (e.g. en0), and pass it in to the launch command (e.g. multipass launch --network en0). Let us know how it goes!

Hi @nhart,

I’m probably doing it wrong, but after installing, according to the linked instructions, for Mac OS on M1, Sonoma 14.0, I don’t get the “Open Shell” option in the app. Here’s what I get:

Multipass_Dock_Options

From there, I didn’t have much luck. For instance, running multipass launch and multipass shell, I can drop into a shell, but it’s not in $HOME, etc.

Am I doing it right? Or has MacOS / Multipass moved on from these instructions?

Cheers,
QM

Hi @qm64, that icon does not appear related to Multipass.

From there, I didn’t have much luck. For instance, running multipass launch and multipass shell, I can drop into a shell, but it’s not in $HOME, etc.

I’m sorry, I don’t understand what you mean. Are you able to successfully get a shell into a VM with multipass shell? The VM does not know about your host users or filesystem, so your $HOME will be different. But you can mount your home from the host to the instance. Multipass does so automatically when you use the primary instance:

$ multipass start
Launched: primary
Mounted '/home/ricab' into 'primary:Home'
$ multipass exec -n primary -- ls Home
[your_stuff]

Hi @ricab,

Thanks, that’s helpful.

Just to close off my previous comments…

I installed multipass-1.12.2+mac-Darwin.pkg from the link on the installation page linked from this page.

Here’s the app that is then available in Launchpad, named Multipass.app, and matches the icon on the Multipass pages.
[Can’t show the Launchpad screenshot, I’m limited to only 1 image due to “new user” limit.]

Here’s the app/icon that shows up in the dock immediately after running the app from Launchpad:
Multipass GUI in Dock

I just want to re-iterate – the instructions to download the installer pkg result in this app / icon, which doesn’t have the “Open shell” option, as shown in my previous comment. I figure I’ve gone astray, but can’t figure it out. Chalk it up to newbie Multipass user.

Yes, your instructions work as you say (multipass start; multipass exec ...). I’ll have to do some more homework reading the docs.

Thanks for your help.

Cheers,
QM

Hey @qm64, you are right about the missing icon in the dock. I thought I recalled a similar bug report, but I couldn’t find it so here’s a new one to track that.

The “Open Shell” option is available in the Multipass icon on the top bar, not on the dock. Can you see that one?

image

Hi @ricab,

Yes, my bad. I see that in the menu bar. Thank!

Cheers,
QM

Hi,

New to multipass, I have successfully installed it on my M1 Mac and played around a little bit. Now a couple of questions:

  1. Where do I find the actual VM files?
  2. Along that same line how do I backup my VMs
  3. How do I cleanup DHCP Leases that have been created for instances that I no longer have.
  4. I somehow got a primary VM but no mount. Didn’t even create that one.

Lastly what is the whole LXD, LXC topic about?

I am used to using docker but like the idea of a full VM which makes things easier with Database backup etc. or so I am told due to being able to backup the whole VM instead of having to do database dumps but I have yet to learn so much about multipass VMs that it seems a little bit daunting.

Appreciate the help and the great explanations that have already been posted.

Hi @backupgeek,

On macOS, multipass stores its data in /var/root/Library/Application\ Support/multipassd by default. You can change this with MULTIPASS_STORAGE.

Multipass does not currently support backing up VMs, but you can backup the folder above by regular means.

With the next release, Multipass will support VM snapshots, which can be used to recover when something goes wrong with the VM itself. However, they are stored in the same place as the VM images, so not suitable as backup against disk corruption and the like.

In normal operation, you shouldn’t have to worry about that. However, that’s sometimes useful as macOS get confused with repeated or excessive leases. You can clean them up by deleting or pruning the file /var/db/dhcpd_leases.

The primary instance is just an implicit instance for some commands like start, stop, and shell, when you don’t specify arguments.

Be sure to have a look at our docs for more, but I think you’ll find that it is pretty easy to learn and use :slight_smile: Hope you enjoy Multipass!

Thank you so much for the clarification! Has helped me a lot to gain a better understanding!
Multipass is really awesome!

1 Like

I just tried installing Multipass on my new Macbook Pro M3 and Sonoma 14.2.1 but I am not able to even create an Ubuntu VM - it just hang for a long time and then print an timeout error message.
How can I get past this problem???

Is there some updated guide for M3 macs?

I just tried installing multipass on my brand new Macbook Pro M3 with MacOS 14.2.1 and nothing seem to work. Trying to create/start an Ubuntu VM just hang and eventually reports an timeout…

Does multipass at all work on M3?

Hi @tristpost

It looks like it is related to https://github.com/canonical/multipass/issues/3308 .

Can you try https://github.com/canonical/multipass/issues/3308#issuecomment-1915745772 the test package and let us know if it works for you? It worked for many other m3 macs which did not work before.