How to use the primary instance

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

See also: shell, mount, client.primary-name.

Multipass offers a quick Ubuntu instance with a simple multipass shell command, or a click on the Open Shell button in the GUI. This is achieved with a special primary instance that is automatically created when it does not exist and the user tries to start or shell into it.

When automatically created, the primary instance gets the same properties as if launch was used with no arguments, except for the name (primary by default). In particular, this means that the instance is derived from the latest Ubuntu LTS image and configured with the default CPU, disk, and memory.

The instance can also be launched normally, like any other. This provides one way to fine-tune its properties (e.g. multipass launch --name primary --cpus 4 eoan). Alternatively, another instance can be set as primary (see below).

There can be only one primary instance at any moment. If it exists, it is always listed first in the output of list and info.

Steering the primary instance

The primary instance can be controlled in a dedicated area in the GUI. Buttons to start, stop, and open a shell into it are available.

On the command line, it is used as the default when no instance name is specified in shell , start , stop , restart , and suspend. When issuing one of these commands with no positional arguments, the primary instance is targeted. Its name can still be given explicitly wherever an instance name is expected (e.g. multipass start primary).

Automatic home mount

When launching the primary instance, whether implicitly or explicitly, Multipass automatically mounts the calling user’s home inside it, in the folder Home. As with any other mount, it can be unmounted with multipass umount. For instance, multipass umount primary will unmount all mounts made by Multipass inside primary, including the auto-mounted Home.

On Windows mounts are disabled by default for security reasons. See multipass set and local.privileged-mounts for information on how to enable them if needed.

Changing the primary instance

The primary instance is identified as such by its name. The name that designates an instance as the primary one is determined by a configuration entry with the key client.primary-name. In other words, while primary is the default name of the primary instance, it can be changed with multipass set client.primary-name=<custom_name>.

This setting allows transferring primary status among instances. The primary name can be configured independently of whether instances with the old and new names exist. If they do, they lose and gain primary status accordingly.

This provides a means of (de)selecting an existing instance as primary. For example, after multipass set client.primary-name=chopin, the primary instance would be called chopin. A subsequent multipass start would start chopin if it existed, and launch it otherwise.


Here is a little demo of how Multipass handles the primary instance:

$ multipass set client.primary-name=first
$ multipass start
Launched: first
Mounted '/home/ubuntu' into 'first:Home'
$ multipass stop
$ multipass launch eoan
Launched: calm-chimaera
$ multipass set client.primary-name=calm-chimaera
$ multipass suspend
$ multipass set client.primary-name=chopin
$ multipass start
Launched: chopin
Mounted '/home/ubuntu' into 'chopin:Home'
$ multipass list
Name                    State             IPv4             Image
chopin                  Running     Ubuntu 18.04 LTS
calm-chimaera           Suspended         --               Ubuntu 19.04
first                   Stopped           --               Ubuntu 18.04 LTS

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

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