About this Install Guide

This guide is intended to get you up and running with this tool quickly with the most common settings. For a thorough review of all options, refer to the official documentation.

Note

A computer running macOS with Apple Silicon or an Arm Linux computer with KVM enabled is required to complete the installation.

Multipass provides cloud style virtual machines (VMs). Multipass is popular among developers for efficient, local testing. When run on macOS with Apple Silicon or on Linux with a Raspberry Pi 5, Multipass provides a similar experience to cloud instances. A local, software compatible equivalent of an Arm cloud instance on your desk with good performance is an important option for developers.

Multipass provides a clear CLI to easily start virtual machine instances, do development tasks, and clean the VMs from your computer.

Before you begin

Multipass runs on a variety of platforms and host operating systems. The information below covers running Multipass on macOS with Apple Silicon and Arm Linux with the goal of creating a compatible Ubuntu Linux environment for developers working on cloud instances.

Multipass uses the terms virtual machine and instance synonymously.

Installation on macOS

Download

Download Multipass for macOS.

    

        
        
            wget https://github.com/canonical/multipass/releases/download/v1.12.0/multipass-1.12.0+mac-Darwin.pkg
        
    

Install

Install the download using the package command.

    

        
        
            sudo installer -pkg  multipass-1.12.0+mac-Darwin.pkg -target /
        
    

The getting started instructions below use the command line interface. Multipass installs a tray icon for those who want to access basic features from the user interface.

Image Alt Text: Connect

Multipass is now installed. Proceed to Get Started with Multipass .

Installation on Arm Linux

Multipass can be used on Arm Linux computers such as the Raspberry Pi 5.

Running Multipass on Linux requires the KVM hypervisor. KVM does not typically work on virtual machines, it requires bare metal.

The instructions have been tested on a Raspberry Pi 5 running Raspberry Pi OS and Ubuntu.

Check KVM

Install and run the kvm-ok command to confirm KVM is available.

Install kvm-ok on Debian based Linux distributions using:

    

        
        
            sudo apt install cpu-checker -y
        
    

To check if KVM is available run:

    

        
        
            kvm-ok
        
    

If KVM is available the output will be similar to:

    

        
        INFO: /dev/kvm exists
KVM acceleration can be used

        
    

If KVM is not available the output will be similar to:

    

        
        INFO: /dev/kvm does not exist
HINT:   sudo modprobe kvm
INFO: For more detailed results, you should run this as root
HINT:   sudo /usr/sbin/kvm-ok

        
    

If KVM is available, proceed with the install.

Install

You may need to install the Snap daemon, snapd, before installing Multipass.

If you are not sure if it is running, execute the command:

    

        
        
            snap version
        
    

If the command is found and version information is printed, then snapd is running.

If you need to install snapd run:

    

        
        
            sudo apt install snapd -y
        
    

LXD is also required for Multipass.

    

        
        
            sudo snap install lxd
        
    
Note

You can select from three Multipass releases: stable, beta, or edge. The default version is stable. Add --beta or --edge to the install command below to select these more recent versions.

    

        
        
            sudo snap install multipass
        
    

Multipass is now installed.

Get started with Multipass

To confirm multipass is installed run the version command.

    

        
        
            multipass version
        
    

If the multipass command is not found, you can add /snap/bin to the Bash search path using:

    

        
        
            export PATH=$PATH:/snap/bin
        
    

Multipass runs Ubuntu images. The last three LTS (long-term support) versions are available. A Docker environment with Portainer is also available as well as a few other images.

To see the available images run the find command. Any of the listed images can be used to create a new instance.

    

        
        
            multipass find 
        
    

The output from find will be similar to the below.

    

        
        Image                       Aliases           Version          Description
20.04                       focal             20231011         Ubuntu 20.04 LTS
22.04                       jammy,lts         20231026         Ubuntu 22.04 LTS
23.04                       lunar             20231025         Ubuntu 23.04
23.10                       mantic,devel      20231011         Ubuntu 23.10

Blueprint                   Aliases           Version          Description
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
ros-noetic                                    0.1              A development and testing environment for ROS Noetic.
ros2-humble                                   0.1              A development and testing environment for ROS 2 Humble.

        
    

Launching instances

The default values for launching instances allocate 1 CPU, create a small disk (5 Gb), and limited memory (1 Gb). By default, the name of the instance is automatically assigned.

Most developers are likely to want to modify the defaults.

Use the command below to launch a virtual machine instance with non-default values.

    

        
        
            multipass launch lts --name m1u --cpus 4 --disk 16G --memory 4G
        
    

Once launched, the command prompt returns and the instance is running in the background.

Connect and use instances

Use the list command to identify created instances. Make note of the instance names as the name is used in other commands.

    

        
        
            multipass list
        
    

To start a command line shell on a running instance use the shell command.

    

        
        
            multipass shell m1u
        
    

To run a specific command from the host on the instance use the exec command. The command to be run comes after the --

    

        
        
            multipass exec m1u -- uname -a
        
    

The uname output will look similar to:

    

        
        Linux m1u 5.15.0-58-generic #64-Ubuntu SMP Thu Jan 5 12:06:43 UTC 2023 aarch64 aarch64 aarch64 GNU/Linux

        
    

Run an application

It’s helpful to demonstrate a few other common commands by downloading and installing an application. To demonstrate file copy, the download is done from macOS and the file is copied into the instance.

Download and install OpenVSCode Server .

On the macOS host computer use wget for the download.

    

        
        
            wget https://github.com/gitpod-io/openvscode-server/releases/download/openvscode-server-v1.79.2/openvscode-server-v1.79.2-linux-arm64.tar.gz
        
    

To copy a file to the instance

    

        
        
            multipass transfer openvscode-server-v1.79.2-linux-arm64.tar.gz m1u:/home/ubuntu
        
    

Now switch to the instance and extract the download and run the application.

If you don’t already have an open shell run.

    

        
        
            multipass shell m1u
        
    

Extract the download.

    

        
        
            tar xvfz openvscode-server-v1.79.2-linux-arm64.tar.gz
        
    

Run the application.

    

        
        
            ./openvscode-server-v1.79.2-linux-arm64/bin/openvscode-server --host=0.0.0.0 --without-connection-token
        
    

Connect to OpenVSCode Server using a browser. From the macOS host computer use the info command to get the IP address of the instance.

The info command prints information about the instance, including the IP address.

    

        
        
            multipass info m1u
        
    

Copy the IP address from the info output and paste it into a browser with port 3000.

Modify the IP address to use your information, for example:

    

        
        http://192.168.64.39:3000

        
    

You now have a running VS Code Server in your Multipass instance with Ubuntu 22.04 running on Arm.

Mount a host directory

To access a large number of files on the host machine without copying or transferring them into the instance use the mount command. This command makes a host directory visible in the instance and all files can be accessed. Modifications made from inside the instance will directly change the files on the host.

For example, to mount a host directory called dev and have it appear in the instance use the mount command.

    

        
        
            multipass mount dev m1u:/home/ubuntu/dev
        
    

There are also options to adjust the user and group IDs as needed to avoid permission problems.

Use the umount command to unmount the directory.

    

        
        
            multipass umount m1u:/home/ubuntu/dev
        
    

Directories can be dynamically mounted and unmounted without stopping the instance.

Stop and Start

Multipass instances can be stopped and started quickly.

To stop the instance.

    

        
        
            multipass stop m1u
        
    

Following the stop the state will change to Stopped on the list command.

To start the instance.

    

        
        
            multipass start m1u
        
    

Cleanup

Multipass instances are easy to delete. There is one extra level of protection to recover deleted instances before they are fully deleted.

Use the delete command to delete.

    

        
        
            multipass delete m1u
        
    

After delete, the state will change to Deleted, but it is still recoverable.

    

        
        
            multipass recover m1u
        
    

Use the purge command to permanently remove all deleted instances.

    

        
        
            multipass purge 
        
    
Note

Purged instances are no longer recoverable.


Feedback

How would you rate the overall quality of this tool quick-install guide?