Running Ubuntu virtual machines on your Mac: creating them, getting in, moving files, keeping them safe, and fixing them when they won't start.
READ-ONLY only looks; safeCHANGES THINGS be carefulON YOUR MAC type it in Terminal on your MacIN THE VM type it inside the virtual machine$ = you type this
Getting started
#1What Multipass is
Multipass runs complete Ubuntu computers, called virtual machines (VMs) or instances, inside your Mac. Each one has its own disk, memory, and network address. Handy for practicing server work safely, away from real client servers.
Words you'll see
Instance
One virtual machine, like ubuntu1. Same thing as "VM."
Image
The Ubuntu version a new instance starts from, like 24.04.
multipassd
The background helper that actually runs the VMs. The multipass command is just its remote control.
Primary
A default instance Multipass can create for you. You don't have to use it.
GOOD TO KNOWOn an Apple Silicon Mac, the VMs run the ARM version of Ubuntu (arm64). Almost everything works the same as on an AWS server; a few downloaded programs come in separate ARM and Intel versions.
The first line is the command; the second is the background helper. If the second line is missing, the helper isn't running (section 8).
Install (new Mac)
brew install --cask multipass
Asks for your Mac password partway through. Ends with multipass was successfully installed!
Update
brew upgrade --cask multipass
Asks for your Mac password. Your VMs and their files are kept.
Run multipass version afterward; both lines should show the new number.
⚠ BEFORE UPDATINGStop your VMs first (multipass stop --all), so none is left suspended. A VM suspended under an older version may refuse to resume after the update. That's the "stuck resume" in Troubleshooting.
One command creates a VM: multipass launch. Everything else is choosing its options. Decide them up front; CPU, memory, and disk can be changed later, but some only with the VM stopped.
The first launch of a version downloads it (a few minutes). Later launches reuse the download.
Launched: test2 = ready. Check it with multipass list.
A message saying it timed out = it may still be finishing. Wait a minute and run multipass list; often it's Running after all.
Step 4 (optional): a setup file for first boot
A cloud-init file is a short text file of instructions the VM follows the first time it starts. Handy for adding your ssh key and installing software, so every new VM starts ready to use.
Make a folder for it, then create the file:
mkdir -p ~/multipass
nano ~/multipass/basic.yaml
⚠ Example only: replace the key line with YOUR public key (from cat ~/.ssh/key-name.pub)
What each part does: #cloud-config must be the very first line. ssh_authorized_keys adds your key for the ubuntu user. package_update refreshes Ubuntu's software list. packages installs each listed program. Spacing matters: use spaces, not tabs, and keep the dashes lined up as shown.
Save (Ctrl+O, Enter), exit (Ctrl+X), then launch with it:
multipass shell ubuntu1 always works and needs no setup. Setting up ssh is worth it too: it lets you use scp, rsync, and the same habits as with your AWS servers.
Step 1: copy your public key (on your Mac)
pbcopy < ~/.ssh/key-name.pub
Step 2: open authorized_keys inside the VM
multipass shell ubuntu1
nano ~/.ssh/authorized_keys
Go to the end with the down arrow, onto a new empty line, and paste with Cmd+V. Save: Ctrl+O, Enter. Exit: Ctrl+X. Then exit to leave the VM.
⚠ DON'T DELETE THE EXISTING LINEThe key already in that file belongs to Multipass itself. It's how multipass shell gets in. Remove it, and multipass shell stops working.
Step 3: add the VM to your ssh config (on your Mac)
Get the address from multipass list, then add an entry with nano ~/.ssh/config, set up the same way as in SSH sheet section 4:
A VM can get a new address after a restart or a Multipass update. If ssh ubuntu1 sits there and times out:
Check the VM is Running and note its address: multipass list.
Update the HostName line in ~/.ssh/config to match.
If you then see REMOTE HOST IDENTIFICATION HAS CHANGED, another VM used that address before. Clear it with ssh-keygen-R 192.168.252.5 (see SSH sheet 6a).
FOR NEW VMsYour key can be added automatically at launch, so steps 1 and 2 aren't needed. See the setup file in section 4.
Two ways: copy files across (they're then separate copies), or mount a Mac folder so the VM sees it live (one folder, two views).
Copy files with multipass transfer
multipass transfer notes.txt ubuntu1:/home/ubuntu/
Upload a file from the folder you're in on your Mac into the VM's home folder
multipass transfer ubuntu1:/home/ubuntu/report.csv .
Download into the folder you're in on your Mac (. = here)
multipass transfer --recursive ~/site ubuntu1:/home/ubuntu/
Copy a whole folder (--recursive is needed for folders)
The VM side always starts with its name and a colon: ubuntu1:.
No output = done. It replaces a file with the same name without asking.
Once ssh is set up (section 5), scp and rsync work too, exactly as on the SSH sheet.
Share a folder live with multipass mount
mkdir -p~/vm-shared
multipass mount ~/vm-shared ubuntu1:/home/ubuntu/shared
The first makes a folder on your Mac; the second shows it inside the VM at /home/ubuntu/shared.
Edit a file on your Mac and the VM sees the change instantly, and the other way around.
See current mounts (read-only): multipass info ubuntu1, under Mounts.
Remove the mount (your files stay on the Mac): multipass umount ubuntu1:/home/ubuntu/shared.
⚠ CAREFULA mount is the same folder, not a copy. Deleting a file inside the VM deletes it from your Mac. Only mount a folder made for the purpose, never your whole home folder.
TIPUse a folder directly in your home folder, like ~/vm-shared. Folders inside Desktop, Documents, or Downloads are protected by macOS privacy settings and may fail to mount.
A clean shutdown, like turning a computer off properly. Next start boots fresh. Takes a little longer to start again, but always works, even after updates.
Suspend: multipass suspend ubuntu1
Freezes the VM's memory to disk, like closing a laptop lid. Resumes exactly where it left off. But that saved memory can fail to load after a Multipass or macOS update, leaving the VM stuck (section 9).
Stop everything at once
multipass stop --all
Do this before updating Multipass, updating macOS, or restarting your Mac. If Multipass shuts down with VMs running, it may suspend them on its own.
Snapshots: a save point you can roll back to
A snapshot records the VM's disk at one moment. Take one before something risky (an upgrade, a big config change); if it goes wrong, restore and you're back to that moment. The VM must be stopped first.
restore asks whether to snapshot the current state first. Say yes unless you're sure you won't want it.
Restoring throws away everything done in the VM since that snapshot.
Note the dot: ubuntu1.before-upgrade = VM name, dot, snapshot name.
⚠ NOT A BACKUPSnapshots live inside the VM's own files. If the VM is deleted (or its disk is damaged), its snapshots go with it. For anything you can't lose, also copy the files out (section 6).
multipassd runs in the background and does the real work. macOS starts it when your Mac starts, and restarts it if it crashes. If it's not running, everymultipass command fails with cannot connect to the multipass socket.
Is it running? (read-only)
sudo launchctl list | grep -i multipass86950-11 com.canonical.multipassd
First column: a number
Running now; that's its process ID.
First column: -
Not running at the moment.
Second column: 0
Last time it stopped, it stopped cleanly.
Second column: any other number
Last time it stopped, it crashed (-11 above). If it keeps crashing, read the log.
The helper isn't running, or keeps crashing. Check it and read the log (section 8). If the log shows a VM failing to resume, see Stuck resume below.
ssh ubuntu1 just sits there, then times out
The VM is stopped, or its address changed. Run multipass list and see section 5.
REMOTE HOST IDENTIFICATION HAS CHANGED
A different VM used that address before. ssh-keygen-R ADDRESS (see SSH sheet 6a).
State shows Unknown
The helper lost track of it. Try multipass start ubuntu1; if that fails, restart the helper (section 8).
Launch says it timed out
Often still finishing. Wait, then multipass list.
multipass shell no longer works, but the VM runs
Multipass's own key was removed from authorized_keys inside the VM (see the warning in section 5).
Stuck resume: a suspended VM that won't start
How you'll know: every multipass command says cannot connect to the multipass socket, and the helper's log shows lines like these, mentioning the VM:
[ubuntu1] Resuming from a suspended state
[ubuntu1] qemu-system-aarch64: error while loading state for instance 0x0 of device 'cpu'
[ubuntu1] qemu-system-aarch64: Error -1 while loading VM state
What's happening: the VM was suspended, and its saved memory no longer loads (often after an update). The helper keeps trying, fails, and crashes. The VM's disk and files are fine.
The fix: delete the saved memory (stored as a save point named suspend inside the VM's disk file), so the VM boots fresh. Its files stay; only what was "open" at the moment of suspending is lost.
⚠ ADVANCED: READ FIRSTThis edits Multipass's own files as root. Do it in order, one command at a time, and stop if any output differs from what's described. Replace ubuntu1 with your VM's name everywhere.