Repository: canonical/multipass

Stars: 9033

README.md Copy Chapter

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 Copy Chapter

| Service | Status |
|------------------------------------------------------|:------------------------------------------------|
| CI | [![Build Status][gha-image]][gha-url] |
| Snap | [![Build Status][snap-image]][snap-url] |
| Codecov | [![Codecov Status][codecov-image]][codecov-url] |

Installation

* On Linux, Multipass is available as a snap:

sudo snap install multipass

* On 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:

brew install --cask multipass

Please 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 Copy Chapter

$ multipass find
Image                       Aliases           Version          Description
20.04                       focal             20240731         Ubuntu 20.04 LTS
22.04                       jammy             20240808         Ubuntu 22.04 LTS
24.04                       noble,lts         20240806         Ubuntu 24.04 LTS
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.

Launch a fresh instance of the current Ubuntu LTS Copy Chapter

$ multipass launch lts
Launched: dancing-chipmunk

Check out the running instances Copy Chapter

$ multipass list
Name                    State             IPv4             Image
dancing-chipmunk        Running           192.168.64.8     Ubuntu 24.04 LTS
phlegmatic-bluebird     Stopped           --               Ubuntu 22.04 LTS
docker                  Running           192.168.64.11    Ubuntu 22.04 LTS
                                          172.17.0.1

Learn more about an instance Copy Chapter

$ multipass info dancing-chipmunk
Name:           dancing-chipmunk
State:          Running
Snapshots:      0
IPv4:           192.168.64.8
Release:        Ubuntu 24.04 LTS
Image hash:     e2608bfdbc44 (Ubuntu 24.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 Copy Chapter

$ multipass shell dancing-chipmunk
Welcome to Ubuntu 24.04 LTS (GNU/Linux 6.8.0-39-generic aarch64)
...

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 Copy Chapter

$ multipass exec dancing-chipmunk -- lsb_release -a
No LSB modules are available.
Distributor ID:  Ubuntu
Description:     Ubuntu 24.04 LTS
Release:         24.04
Codename:        noble

Stop an instance to save resources Copy Chapter

$ multipass stop dancing-chipmunk

Delete an instance Copy Chapter

$ multipass delete dancing-chipmunk

The instance will now show up as deleted:

$ multipass list
Name                    State             IPv4             Image
dancing-chipmunk        Deleted           --               Ubuntu 24.04 LTS
phlegmatic-bluebird     Stopped           --               Ubuntu 22.04 LTS
docker                  Running           192.168.64.11    Ubuntu 22.04 LTS
                                          172.17.0.1

If you want to completely get rid of it:

$ multipass purge

Get help Copy Chapter

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. <!-- TODO: link to guidelines -->

Building Multipass Copy Chapter

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 Copy Section

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 Copy Section

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 Copy Chapter

When contributing, you must adhere to the Code of Conduct.

Copyright Copy Chapter

The code in this repository is licensed under GNU General Public License v3.0.
See LICENSE for more information.

License agreement Copy Chapter

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 Copy Chapter

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 Copy Chapter

- WangYihang/multipass-mcp

Terraform providers Copy Chapter

- todoroff/terraform-provider-multipass
- larstobi/terraform-provider-multipass

Visual Studio Code extensions Copy Chapter

- geoffreynyaga/multipass-run
- levalleyjack/multipass-manager-vscode

Additional information

Multipass documentation

[gha-image]: https://github.com/canonical/multipass/workflows/Linux/badge.svg?branch=main

[gha-url]: https://github.com/canonical/multipass/actions?query=branch%3Amain+workflow%3ALinux

[snap-image]: https://snapcraft.io/multipass/badge.svg

[snap-url]: https://snapcraft.io/multipass

[codecov-image]: https://codecov.io/gh/canonical/multipass/branch/main/graph/badge.svg

[codecov-url]: https://codecov.io/gh/canonical/multipass