File: README.md
What is Multipass?
Multipass is a lightweight VM manager for Linux, Windows and macOS. It's designed for developers who want to spin up a
fresh Ubuntu environment with a single command. It uses KVM on Linux, Hyper-V on Windows and QEMU on macOS to run
virtual machines with minimal overhead. It can also use VirtualBox on Windows and macOS. Multipass will fetch Ubuntu
images for you and keep them up to date.
Since it supports metadata for cloud-init, you can simulate a small cloud deployment on your laptop or workstation.
Project status
| Service | Status |
|---|---|
| CI |  |
| Snap |  |
| Codecov |  |
Installation
On Linux, Multipass is available as a snap:
textsudo snap install multipassOn macOS, download the installer from GitHub.
Alternatively, you can use Homebrew. Please note that this method is not
officially supported, as it is not maintained by the Multipass team, but by the community. Multipass is available as
a cask:textbrew install --cask multipassPlease note that you may be required to enter your password for some sudo operations during installation. You may also
need to disable the firewall to launch a multipass instance successfully on macOS.On Windows, download the installer from GitHub.
For more information, see How to install Multipass.
Usage
Here are some pointers to get started with Multipass. For a more comprehensive learning experience, please check out the
Multipass Tutorial.
Find available images
$ multipass find
Image Aliases Version Description
22.04 jammy 20260515 Ubuntu 22.04 LTS
24.04 noble 20260518 Ubuntu 24.04 LTS
25.10 questing 20260520 Ubuntu 25.10
26.04 resolute,lts,ubuntu 20260520 Ubuntu 26.04 LTS
core:core16 current Ubuntu Core 16
core:core18 current Ubuntu Core 18
core:core20 current Ubuntu Core 20
core:core22 current Ubuntu Core 22
core:core24 current Ubuntu Core 24
core:core26 current Ubuntu Core 26
debian trixie 20260601 Debian Trixie
fedora 20260422 Fedora 44Launch a fresh instance of the current Ubuntu LTS
$ multipass launch lts
Launched: dancing-chipmunkCheck out the running instances
$ multipass list
Name State IPv4 Image
dancing-chipmunk Running 192.168.64.8 Ubuntu 26.04 LTSLearn more about an instance
$ multipass info dancing-chipmunk
Name: dancing-chipmunk
State: Running
Snapshots: 0
IPv4: 192.168.64.8
Release: Ubuntu 26.04 LTS
Image hash: dced94c031cc (Ubuntu 26.04 LTS)
CPU(s): 1
Load: 5.70 4.58 2.63
Disk usage: 3.3GiB out of 4.8GiB
Memory usage: 769.0MiB out of 953.0MiB
Mounts: --Connect to a running instance
$ multipass shell dancing-chipmunk
Welcome to Ubuntu 26.04 LTS (GNU/Linux 7.0.0-22-generic x86_64)
...Don't forget to logout (or Ctrl-D) or you may find yourself heading all the way down Inception levels... ;)
Run commands inside an instance from outside
$ multipass exec dancing-chipmunk -- lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Release: 26.04
Codename: resoluteStop an instance to save resources
$ multipass stop dancing-chipmunkDelete an instance
$ multipass delete dancing-chipmunkThe instance will now show up as deleted:
$ multipass list
Name State IPv4 Image
dancing-chipmunk Deleted -- Ubuntu 26.04 LTSIf you want to completely get rid of it:
$ multipass purgeGet help
multipass help
multipass help <command>Contributing
The Multipass team appreciates contributions to the project, through pull requests, issues, or discussions and questions
on the Discourse forum. Please read the policy sections below carefully
before contributing to the project.
Building Multipass
Please follow the platform-specific build instructions in the files below:
- BUILD.linux.md for Linux
- BUILD.macOS.md for macOS
- BUILD.windows.md for Windows
Generic build tips
Qt version compatibility
Multipass is tested with Qt 6.9.1. Newer patch versions along the 6.9 track (e.g. 6.9.2) should be fine. Newer minor versions may work, but they may cause compatibility issues.
You may use your preferred package manager to install Multipass.
Note that only the official installers are supported.
See the installation guide for details.
For backend support and system requirements, refer to the
Multipass driver documentation.
If you notice outdated information or inconsistencies in these files, please open an issue or, even better, submit a pull request!
You can also reference our GitHub Actions CI to see how Multipass is built and tested across platforms.
Automatic linker selection
Requires (>= CMake 3.29)
To accelerate the build, the build system will attempt to locate and utilize mold or lld (respectively) in place of
the default linker of the toolchain. To override, set
CMAKE_LINKER_TYPE at CMake
configure step.
Code of Conduct
When contributing, you must adhere to the Code of Conduct.
Copyright
The code in this repository is licensed under GNU General Public License v3.0.
See LICENSE for more information.
License agreement
All contributors must sign the Canonical contributor license agreement (CLA),
which gives Canonical permission to use the contributions. Without the CLA, contributions cannot be accepted.
Pull requests
Changes to this project should be proposed as pull requests. Proposed changes will then go through review and once
approved, be merged into the main branch.
Community-led integrations
Multipass MCP Server
Terraform providers
Visual Studio Code extensions
Additional information
File: docs/explanation/about-performance.md
(explanation-about-performance)=
About performance
When considering performance with Multipass, there are two aspects that need to be accounted for:
- the Multipass instance
- the host machine
There are many factors that can affect the performance of the instance and the host. To ensure the best performance of both areas, careful consideration should be given.
Host system
Here you'll find some considerations and recommendations on allocating host system resources.
CPUs/cores/threads
When provisioning a Multipass instance, you should take into account the host's CPU speed and the number of cores and threads. You should also consider the number of instances that will be running simultaneously.
The number of cores allocated to an instance and the number of running instances will greatly impact processes running on the host machine itself. As general guidance, you should reserve at least two threads, that will not be allocated to running instances.
Of course, there may be other factors in different host machines that can greatly affect how well they perform when running Multipass instances.
Memory usage
The amount of memory allocated to instances can also greatly impact the host system.
You should not overallocate memory for running Multipass instances, as this can cause the host to appear slower than normal or become unresponsive.
We recommend that you reserve at least 4GB of memory for the host, but this also depends on the workload of the host itself, so more memory may be needed.
Multipass instances
Here you'll find some considerations and recommendations on allocating resources to your instances.
CPUs
The number of CPUs allocated to a Multipass instance has a direct impact on the performance of the instance itself. Generally, the more CPUs allocated, the more potential for better performance in the instance. This depends heavily on the workload intended for instance.
Memory
As with cores, the amount of memory allocated to a Multipass instance will also have a direct on its performance. This is also dependent on the intended workload of instances. Naturally, more memory intensive workloads provide much larger gains in performance if more memory is allocated to the instance.
File: docs/explanation/about-security.md
(explanation-about-security)=
About security
See also: Authentication, How to authenticate users with the Multipass service,
authenticate,local.passphrase
**WARNING**
Multipass is primarily intended for development, testing, and local environments. It is not intended for production use. Review the security considerations in this page carefully before deploying your Multipass VMs.Multipass runs a daemon that is accessed locally via a Unix socket on Linux and macOS, and over a TLS socket on Windows. Anyone with access to the socket can fully control Multipass, which includes mounting host file systems or to tweaking the security features for all instances.
Therefore, make sure to restrict access to the daemon to trusted users.
Local access to the Multipass daemon
The Multipass daemon runs as root and provides a Unix socket for local communication. Access control for Multipass is initially based on group membership and later by the user's TLS certificate when accepted by providing a set passphrase.
The first user to connect that is a member of the sudo group (or wheel/adm, depending on the OS) will automatically have their TLS certificate imported into the Multipass daemon and will be authenticated to connect. After this, any other user connecting will need to authenticate first by providing a passphrase set by the administrator.
File: docs/explanation/authentication.md
(explanation-authentication)=
Authentication
See also: How to authenticate users with the Multipass service
Before executing any commands, Multipass requires users to authenticate with the service. Multipass employs an authentication process based on x509 certificates signed by elliptic curve (EC) keys, powered by OpenSSL, to authenticate users. When a user connects, Multipass validates the certificate to ensure only verified users can access the service.
````{tab-item} Linux
Linux and macOS hosts currently use a Unix domain socket for client and daemon communication. Upon first use, this socket only allows a client to connect via a user belonging to the group that owns the socket. For example, this group could be `sudo`, `admin`, or `wheel` and the user needs to belong to this group or else permission will be denied when connecting.
After the first client connects with a user belonging to the socket's admin group, the user's OpenSSL certificate will be accepted by the daemon and the socket will then be open for all users to connect. Any other user trying to connect to the Multipass service will need to authenticate with the service using the previously set [`local.passphrase`](/reference/settings/local-passphrase).
````
````{tab-item} macOS
Linux and macOS hosts currently use a Unix domain socket for client and daemon communication. Upon first use, this socket only allows a client to connect via a user belonging to the group that owns the socket. For example, this group could be `sudo`, `admin`, or `wheel` and the user needs to belong to this group or else permission will be denied when connecting.
After the first client connects with a user belonging to the socket's admin group, the user's OpenSSL certificate will be accepted by the daemon and the socket will then be open for all users to connect. Any other user trying to connect to the Multipass service will need to authenticate with the service using the previously set [`local.passphrase`](/reference/settings/local-passphrase).
````
````{tab-item} Windows
The Windows host uses a TCP socket listening on port 50051 for client connections. This socket is open for all to use since there is no concept of file ownership for TCP sockets. This is not very secure in that any Multipass user can connect to the service and issue any commands.
To close this gap, the user will now need to be authenticated with the Multipass service. To ease the burden of having to authenticate, the user who installs the updated version of Multipass will automatically have their clients authenticated with the service. Any other users connecting to the service will have to use authenticate using the previously set [`local.passphrase`](/reference/settings/local-passphrase).
````File: docs/explanation/driver.md
(explanation-driver)=
Driver
See also: How to set up the driver,
local.driver, Instance, Platform
A driver is the technology through which Multipass emulates a running machine. It corresponds to a hypervisor or intermediary technology to run virtual machines. The driver is sometimes also referred to as "backend".
Multipass relies on a driver to operate. It supports multiple drivers, but it runs with a single driver at a time. There is a Multipass setting to select the driver: local.driver.
On some platforms, it is possible to select a driver during installation. Until it is manually set, a platform-appropriate default driver is used.
Supported drivers
Different sets of drivers are available on different platforms:
- On Linux, Multipass can be configured to use QEMU. As of Multipass version 1.16, LXD and libvirt are no longer available.
- On macOS, the options are QEMU, the Apple Virtualization framework (AppleVZ), and VirtualBox. As of Multipass version 1.13, Hyperkit is no longer available.
- On Windows, Multipass uses Hyper-V (only available on Windows Pro) or VirtualBox.
Default drivers
When Multipass is installed, the following drivers are selected by default:
- On Linux and macOS, QEMU is used.
- On Windows, the default driver depends on the OS version:
- Hyper-V on Windows Pro
- VirtualBox on Windows Home
Instance scopes
In general, Multipass instances are tied to a single driver, with the {ref}explanation-driver-exceptions listed below. The set of instances that were launched with one driver are available only while that driver is in use.
When a new driver is selected, Multipass switches to a separate instance scope. There, the set of existing instances is empty to begin with. Users can launch instances with the same name in different drivers and changes to instances with one driver have no effect on the instances of another.
Nonetheless, instances are preserved across drivers. After switching back to a previously-used driver, Multipass restores the corresponding instance scope. It attempts to restore the state instances were in just before the switch and users can interact with them just as before.
(explanation-driver-exceptions)=
Exceptions
There are two exceptions to the above:
- On macOS, stopped Hyperkit instances are automatically migrated to QEMU by Multipass's version 1.12 or later (see How to migrate from Hyperkit to QEMU on macOS).
(driver-feature-disparities)=
Feature disparities
While we strive to offer a uniform interface across the board, not all features are available on all backends and there are some behaviour differences:
| Feature | Not supported on... | Notes |
|---|---|---|
| Native mounts | This affects the --type option in the mount command). |
|
| Snapshots | This affects the snapshot command. |
|
| Suspend | This affects the suspend command. |
There are also feature disparities depending on the host platform. See [Platform](/explanation/platform) for more details.File: docs/explanation/id-mapping.md
(explanation-id-mapping)=
ID mapping
See also:
mount, Mount, How to share data with an instance
ID mapping refers to the process of aligning user or group IDs between the host system and an instance when mounting directories. This alignment ensures that the files mounted from the host to the instance retain consistent ownership and permission attributes.
Since ID mappings take effect from host to instance, as well as in the opposite direction, they must be defined as a one-to-one relationship, meaning that each user or group ID on the host system should be mapped directly to a single user or group ID within the virtual machine, and vice versa.
For example, the user ID 501 can be mapped to the user ID 1000 in the "foo" instance:
multipass mount ~/Documents foo:Documents -u 501:1000On the other hand, it is not possible to map this same user to a second user ID within the instance, as Multipass would be unable to determine which user ID to assign on the instance to a file with a user ID of 501 on the host system. The following command defines an invalid mount, since more than one ID on the host is mapped to the same ID in the instance:
multipass mount ~/Documents foo:Documents -u 501:1000 -u 502:1000
Instead, a valid mount that maps two different user IDs could be defined as follows:
multipass mount ~/Documents foo:Documents -u 501:1000 -u 502:1001The same logic also applies when trying to map a single user or group ID in an instance to two different IDs on the host.
File: docs/explanation/image.md
(explanation-image)=
Image
Multipass uses images (short for disk images or system images) tuned for cloud usage to spin up VMs.
You can use multipass find to view a list of the available images. These images are obtained from different sources, such as:
- Ubuntu Cloud Images: https://cloud-images.ubuntu.com/
- Ubuntu CD Images: https://cdimages.ubuntu.com/
and more.
You can also launch images from a file or URL, as long as they provide the tools required to deploy a cloud. The key requirements are:
- cloud-init
- SSH
For more information on the system requirements for a particular image, refer to official documentation (for example: Ubuntu Core system requirements).