Skip to content

[docs] AppleVZ docs #4787

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sharder996 wants to merge 4 commits into
base: main
Choose a base branch
from
Open

[docs] AppleVZ docs #4787

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1e422fe
[docs] Add references to applevz driver
sharder996 Apr 2, 2026
805a1d5
[docs] Invert table of feature parity
sharder996 Apr 2, 2026
57bb05a
[docs] Remove meaningless sentence
sharder996 Apr 2, 2026
ba40c5e
[docs] Add AppleVZ synonym
sharder996 Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions docs/explanation/driver.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ On some platforms, it is possible to select a driver during installation. Until
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 and VirtualBox. As of Multipass version 1.13, Hyperkit is no longer available.
- On macOS, the options are QEMU, the Apple Virtualization framework, and VirtualBox. As of Multipass version 1.13, Hyperkit is no longer available.
Copy link
Copy Markdown
Contributor

@geoffreynyaga geoffreynyaga Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor request. Since we use both the full name and the abbreviation interchangeably throughout the docs, I'd suggest introducing both together at first mention so readers always have the reference:

+ the Apple Virtualization framework (AppleVZ), ...

Quick question: I know that Apple uses VZ as class prefix throughout its codebase. Are apple-vz/AppleVZ terms that Apple uses officially, or are they Multipass-specific shorthands derived from that prefix? Knowing this will help us write a more accurate explanation in the docs down the line.

Copy link
Copy Markdown
Collaborator Author

@sharder996 sharder996 Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have found no references to any other AppleVZ mutations in the Apple docs. Its always referred to by its full moniker.

Copy link
Copy Markdown
Collaborator

@ricab ricab Apr 8, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will the setting value be named as applevz? If so, better tie the two together somewhere in the docs (not sure where)

Copy link
Copy Markdown
Collaborator Author

@sharder996 sharder996 Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is mentioned in

multipass/docs/how-to-guides/customise-multipass/set-up-the-driver.md

Lines 35 to 48 in ba40c5e

## Install an alternative driver
`````{tab-set}
````{tab-item} macOS
:sync: macOS
An alternative option is to use the Apple Virtualization framework.
To switch the Multipass driver to AppleVZ, run this command:
```{code-block} text
sudo multipass set local.driver=applevz
```

- On Windows, Multipass uses Hyper-V (only available on Windows Pro) or VirtualBox.

## Default drivers
Expand Down Expand Up @@ -46,9 +46,11 @@ There are two exceptions to the above:

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 | Only supported on... | Notes |
| Feature | Not supported on... | Notes |
|--- | --- | --- |
| **Native mounts** | <ul><li>Hyper-V</li><li>QEMU</li></ul> | This affects the `--type` option in the [`mount`](/reference/command-line-interface/mount) command). |
| **Native mounts** | <ul><li>AppleVZ</li><li>VirtualBox</li></ul> | This affects the `--type` option in the [`mount`](/reference/command-line-interface/mount) command). |
| **Snapshots** | <ul><li>AppleVZ</li></ul> | This affects the [`snapshot`](/reference/command-line-interface/snapshot) command. |
| **Suspend** | <ul><li>AppleVZ</li></ul> | This affects the [`suspend`](/reference/command-line-interface/suspend) command. |

<!-- old formatting
- **Native mounts** are supported only on Hyper-V and QEMU. This affects the `--type` option in the [`mount`](/reference/command-line-interface/mount) command).
Expand Down
14 changes: 12 additions & 2 deletions docs/how-to-guides/customise-multipass/set-up-the-driver.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,17 @@ By default, Multipass on Windows uses the `hyperv` driver.
````{tab-item} macOS
:sync: macOS

An alternative option is to use VirtualBox.
An alternative option is to use the Apple Virtualization framework.

To switch the Multipass driver to AppleVZ, run this command:

```{code-block} text
sudo multipass set local.driver=applevz
```

From now on, all instances started with `multipass launch` will use the Apple Virtualization framework behind the scenes.

An additional option is to use VirtualBox.

To switch the Multipass driver to VirtualBox, run this command:

Expand Down Expand Up @@ -229,7 +239,7 @@ You can then open, say, https://localhost:8081/, and the service running inside
````{tab-item} Linux
:sync: Linux

This option only applies to macOS systems.
This option only applies to macOS and Windows systems.

````

Expand Down
6 changes: 6 additions & 0 deletions docs/how-to-guides/install-multipass.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,12 @@ You've installed Multipass. Time to run your first commands! Use `multipass vers

You've installed Multipass. Time to run your first commands! Use `multipass version` to check your version or `multipass launch` to create your first instance.

Multipass defaults to using QEMU as its virtualisation provider. If you'd like to use AppleVZ, you can do so using the following command:
Copy link
Copy Markdown
Contributor

@geoffreynyaga geoffreynyaga Apr 8, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a small fix.
We should use US english for consistency. I'd recommend we swap virtualisation with virtualization. This also helps with consistency even when we reference AppleVZ.

Note: US english is now recommended internally https://docs.ubuntu.com/styleguide/en/#spelling and the word 'virtualization' is specifically listed under the "Other common terms" section. The functionality is already implemented in the Multipass repo, but we have not enabled the check on CI (it requires effort to update all pages). Hint: If you run make run locally, you should see a docs/.sphinx/styles/Canonical/000-US-spellcheck.yml file.

Copy link
Copy Markdown
Collaborator Author

@sharder996 sharder996 Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I used virtualization explicitly because its part of the name of the framework, but if you want I can find/replace all instances of virtualisation with the former.


```{code-block} text
multipass set local.driver=applevz
```

```{seealso}
[How to set up the driver](/how-to-guides/customise-multipass/set-up-the-driver), [How to use a different terminal from the system icon](/how-to-guides/customise-multipass/use-a-different-terminal-from-the-system-icon)
```
Expand Down
2 changes: 1 addition & 1 deletion docs/how-to-guides/manage-instances/create-an-instance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ This feature is only supported for images with [`cloud-init` support for v2 netw

* on Linux, with QEMU (*from Multipass 1.15 onward*)
* on Windows, with both Hyper-V and VirtualBox
* on macOS, with the QEMU and VirtualBox drivers
* on macOS, with the QEMU, AppleVZ, and VirtualBox drivers

The `--network` option can be given multiple times to request multiple network interfaces beyond the default one, which is always present. Each time you add the `--network` option you also need to provide an argument specifying the properties of the desired interface:

Expand Down
2 changes: 1 addition & 1 deletion docs/how-to-guides/manage-instances/modify-an-instance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ On the other hand, it's always possible to fetch properties for all instances. U
```

```{note}
Modifying instance settings is not supported when using the Hyperkit driver, which has been deprecated in favour of QEMU. The QEMU and VirtualBox drivers on Intel-based macOS hosts do support instance modification.
Modifying instance settings is not supported when using the Hyperkit driver, which has been deprecated in favour of QEMU.
```

## Set the status of an instance to primary
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/command-line-interface/networks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ At this time, `multipass networks` can only find interfaces in the following sce

- on Linux, with QEMU
- on Windows, with both Hyper-V and VirtualBox
- on macOS, with the QEMU and VirtualBox drivers
- on macOS, with the QEMU, AppleVZ, and VirtualBox drivers

For example, on Windows with Hyper-V the `multipass networks` command returns:

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/settings/local-driver.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ A string identifying the hypervisor back-end in use.

- `qemu` on Linux
- `hyperv` and `virtualbox` on Windows
- `qemu` and `virtualbox` on macOS 10.15+
- `qemu`, `applevz`, and `virtualbox` on macOS 13.3+

## Default values

Expand Down
Loading