Virtual machines
FreeThe Virtual machines page runs local VMs with QEMU, a free open-source emulator. You create a machine, pick an installer image, start it, and it opens in a window of its own. That lets you test a website on another operating system or rebuild a server without a second computer. The feature is free and carries the Beta badge in the sidebar: it works, but is not mature in every part yet.
QEMU is not part of WebDonkey. The app installs it with Homebrew and calls the command-line program, the same way it does with git or composer. WebDonkey manages the machines, but shows their screen in QEMU's window rather than inside the app.
What you do here
- Set up the VM engine
- Download or import images
- Create a VM
- Set the window size
- Start, stop and manage VMs
- Add Windows and other systems
Page layout
You find the page in the sidebar in the Tools group. At the top are the title and New VM. As long as the VM engine is missing, you only see the VM engine required card. After that come:
- the list of machines with the number of all and of running machines, and next to it VM engine ready, the QEMU version, your Mac's architecture and, where it applies, Hardware accelerated
- Downloaded images: your image library
- Download an image: the catalog of distributions
- Not downloadable automatically: systems whose image you fetch yourself
- a pointer to DistroWatch for everything else
On the command line you manage VMs with wd vms, see More tools.
Free and Premium
Virtual machines are included on Free and Premium without limits.
Set up the VM engine Free
Before you can create a VM, WebDonkey needs QEMU on your Mac. That is why you see the VM engine required card the first time you open the page. One click installs QEMU with Homebrew, exactly as if you ran the command yourself.
Where to find it
Sidebar › Tools › Virtual machines. The card appears as long as QEMU is missing.
How to do it
- Open Virtual machines.
- Under This command will run, the card shows the command
brew install qemu. - Click Install engine. The installation takes roughly 1 GB and a few minutes.
- While it installs, a bar runs and below it the latest line of the output.
- Once QEMU is installed, the card disappears. At the top of the list it says VM engine ready.
Homebrew would upgrade other packages
If Homebrew has to upgrade formulae for QEMU that are already on your Mac, WebDonkey changes nothing at first. The Homebrew would upgrade something else too confirmation lists the affected formulae with their old and new versions. Only with Upgrade and install does the installation run with these upgrades.
What you see afterwards
The list header shows:
| Display | Meaning |
|---|---|
| VM engine ready | QEMU is installed. |
QEMU 9.1.2 |
The installed version. |
| Host: … | Your Mac's architecture, aarch64 on Apple silicon, x86_64 on Intel. |
| Hardware accelerated | macOS can accelerate VMs. This applies when guest and Mac share the same architecture. |
Guests with a different architecture run emulated: correctly, but much more slowly. When you create one, a note points this out.
What happens in the background
WebDonkey runs brew install qemu. QEMU ends up where Homebrew keeps its packages, not in WebDonkey's data folder. For ARM guests WebDonkey uses the UEFI firmware that Homebrew's QEMU package ships.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| Homebrew is required to install the engine automatically. with the link brew.sh | Homebrew is not installed. | Install Homebrew via brew.sh, then open the page again. |
| Error message under the card, Retry button | The installation failed. The message names the reason. | Fix the reason, such as network or disk space, then Retry. |
| Homebrew would upgrade something else too | Homebrew would have to upgrade existing formulae. | Read the list, then Upgrade and install or cancel. |
See also
Download and import images Free
An image is the installer file of an operating system, usually an .iso. Everything about images happens on the page itself, not in the create dialog: downloading, importing and deleting. The images sit in a shared library and are used by all VMs. One Ubuntu image is enough for any number of machines.
Where to find it
Sidebar › Tools › Virtual machines, below the list of machines. The sections appear once the VM engine is set up.
How to do it
Download from the catalog
- Scroll to the Download an image section. It is open as soon as the page is. Hide catalog collapses it, Show catalog opens it again.
- Search with Search… if needed. The catalog is grouped into Desktop and Server & minimal.
- If there are several versions, pick one in the selector (Version). The newest is preselected.
- Click Download. A bar shows the progress with the downloaded and total size. Cancel stops the download.
- Once the image is there, the row says Downloaded, and it appears under Downloaded images.
You can start several downloads at once and leave the page meanwhile. Finished and failed downloads report in the bell.
Import your own file
- Under Downloaded images, click Import file….
- Pick the file (
.iso,.imgor.dmg), for example a Windows image or your own build.
The file is copied into the library, not just linked. Tidying up your Downloads folder therefore breaks no VM.
Delete an image
- Click Remove (trash can) in the image's row.
- Confirm Delete image? with Remove.
VMs already installed from it keep running, because the image is only needed for installation.
The catalog
Which distributions the catalog shows depends on your Mac's architecture:
| Mac | Desktop | Server & minimal |
|---|---|---|
| Apple silicon | Ubuntu Desktop, Fedora Workstation | Ubuntu Server, Debian, Alpine Linux, Fedora Server, Rocky Linux |
| Intel | additionally CachyOS, Linux Mint, Kubuntu | additionally Arch Linux |
WebDonkey reads the versions from the projects' official release directories, so they do not go stale between two app updates. If a version cannot be determined right now, for example without internet, the row shows the project's Website button instead of Download. While it looks them up, Checking versions… appears above the catalog.
The catalog is curated, not complete. For everything else, DistroWatch at the end of the page leads to an overview of all distributions. Download the image there and add it with Import file….
What happens in the background
- Downloads go over HTTPS. Every file is checked against the SHA-256 checksum the project itself publishes. If it does not match, WebDonkey deletes the file.
- The library lives in WebDonkey's data folder at
~/Library/Application Support/WebDonkey/isos/. The size of all images is shown above the list ("x GB total").
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| Red message above the catalog | The download failed, for example because of a wrong checksum or a network error. | Download again. |
| Website instead of Download | The version could not be determined. | Open the page again later, or download the image from the website and import it. |
| Nothing matches. | The search matches no distribution. | Change the search term. |
| A distribution is missing | It is not in the catalog for your Mac's architecture. | Download the image yourself and import it. |
See also
Create a VM Free
New VM opens the New virtual machine dialog. All you need is a name and, for the first installation, an image from your library. Everything else has sensible defaults, and your Mac's limits are shown under each field.
Where to find it
Virtual machines page › top right New VM. With an empty list, the button also sits in the middle. It only appears once the VM engine is set up.
How to do it
- Click New VM.
- Enter a Name, for example "Ubuntu Server".
- Under Installer ISO, pick an image from your library. If it is still empty, Go to the image library takes you to the images on the page (see Download and import images). Manage images ↓ goes there too.
- Check Operating system and Architecture. For an image whose file name gives both away, they are fixed (from the selected image). Otherwise you pick them.
- Set the hardware: Memory, CPU cores, Disk size.
- Optional: SSH port forward and Window size.
- Click Create VM.
The machine appears in the list, stopped. Start it with the switch in the Status column (see Start, stop and manage).
Fields and options
| Field | Meaning | Default |
|---|---|---|
| Name | Name of the machine in the list. Required. | empty |
| Installer ISO | The image for the first boot. Eject it after installation. No installer (boot from disk) starts from the machine's own disk without an image. | empty |
| Operating system | Linux, Windows, BSD or Other. | Linux |
| Architecture | ARM64 (aarch64) or Intel/AMD (x86_64). If it differs from your Mac, the guest runs emulated and the dialog warns you. | your Mac's architecture |
| Memory | In GB, in steps of 0.5 GB. 2 GB always stay reserved for macOS. | 4 GB |
| CPU cores | At most as many as your Mac has. | 2 |
| Disk size | In GB, at least 4. The free space is shown below the field. The file only grows when needed, so a 64 GB disk takes little space at first. | 32 GB |
| SSH port forward | Optional. Enter 2222 and you reach the guest with ssh -p 2222 localhost once SSH runs in the guest. Ports from 1024 are allowed. |
empty |
| Window size | The resolution the VM starts with, see Window size. | 1280×800 |
Values in the number fields are clamped to the allowed limits when you leave the field. Create VM only works with a name.
What happens in the background
- WebDonkey creates a folder of its own for the machine under
~/Library/Application Support/WebDonkey/vms/, holding the virtual diskdisk.qcow2. The qcow2 format grows with its content. - The disk size is fixed after creation. Resizing needs changes inside the guest too.
- The dialog keeps your input if you switch pages in between.
Changing it later
Edit (pencil in the row) opens Edit VM with the same fields. The machine has to be stopped for changes. The disk size is only displayed there.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| No images in your library yet. | You have not downloaded an image yet. | Go to the image library and download or import an image. |
| Yellow note about the guest architecture | Guest and Mac have different architectures. | Pick an image for your Mac's architecture, or accept the slower emulation. |
| Create VM stays grey | No name entered. | Enter a name. |
See also
Window size Free
The Window size setting decides how large a VM's window opens. The QEMU window has no width or height option of its own: it is exactly as large as the screen the guest thinks it has. If nobody tells the guest, it picks something small, usually 1024×768. So this setting tells the guest which resolution to prefer.
Where to find it
In the New virtual machine and Edit VM dialogs, field Window size. Afterwards the chosen size is shown in the list's Window size column, or under the resources when the window is narrow.
How to do it
- Open the create dialog or Edit. The VM has to be stopped for editing.
- Pick one of the sizes or Custom.
- Tick Open in fullscreen if you like.
- Save and start the VM.
Fields and options
| Option | Meaning |
|---|---|
1280×800, 1600×900, 1920×1080, 2560×1440 |
Fixed sizes in one click. 1280×800 is the default for new VMs. |
| Guest decides | The guest picks for itself. Some installers insist on their own mode. |
| Custom | Your own Width and Height in pixels. The width lies between 640 and 7680 and is rounded down to a multiple of 8, the height lies between 480 and 4320. |
| Open in fullscreen | Starts the machine in macOS fullscreen instead of a window. The list then shows Fullscreen. |
What happens in the background
WebDonkey passes the resolution to the virtual graphics card QEMU presents to the guest. The guest reads it at boot as its preferred screen mode, and the window follows. You can drag the window afterwards, and the picture scales along.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| The window is smaller for the first few seconds | The firmware screen at boot has a fixed size. | Wait until the system has started. |
| The window has a different size after booting | The guest changed its resolution itself. The setting is the starting default, not a constraint. | Set the resolution inside the guest. |
| The size cannot be changed | The VM is running. | Stop the VM, then Edit. |
See also
Start, stop and manage Free
Each VM is a row in the list, with architecture, resources, window size and status. The switch in the Status column starts and stops the machine. Next to it are notes, edit and delete. WebDonkey keeps checking whether a VM is running: if you shut the guest down from inside, the list notices on its own.
Where to find it
Sidebar › Tools › Virtual machines, the list at the top of the page.
How to do it
Start and stop
- Turn on the machine's switch in the Status column. The VM boots and opens its own window, where you operate the guest system.
- To stop it, turn the switch off. WebDonkey then presses the virtual power button, and the guest system shuts down cleanly.
Eject the ISO after installation
Once the installation is done, the VM should boot from its own disk rather than into the installer again.
- Stop the VM.
- In the row, click Eject ISO after ISO and the image's name.
- Confirm Eject ISO?.
The image file is kept, and you can attach it again later with Edit.
Notes
- Click the note icon (Notes).
- Write in the field what the VM is for, which login it was set up with and what still needs doing inside it.
- Click Save.
Notes can be edited while the VM runs too. A machine with a note shows the icon highlighted.
Delete
- Stop the VM.
- Click the trash can (Delete).
- Confirm Delete VM? with Remove. Machine and virtual disk are permanently deleted.
List columns
| Column | Content |
|---|---|
| Machine | Name, architecture (aarch64 or x86_64), with an SSH forward the ready command such as ssh -p 2222 localhost with Copy command and the note once SSH is running in the guest, plus the attached image with Eject ISO. |
| Resources | Cores, memory and the actual disk usage against the configured size, such as "4.5 GB / 32 GB". |
| Window size | The configured size or Guest decides, plus Fullscreen. With a narrow window this sits under the resources. |
| Status | Switch to start and stop, with the state Running or Off. |
| Actions | Notes, Edit and Delete. Edit and Delete are locked while the VM runs. |
Above the list are Total and Running, the number of all and of running machines.
What happens in the background
- WebDonkey does not store a VM's state but reads it from the process list every few seconds. So the display is right even after a restart of your Mac.
- Stopping sends the QEMU process the signal to quit. QEMU passes it on to the guest as a press of the power button.
- The SSH forward only listens on this Mac (
localhost), not on the network. - Notes are only stored locally in WebDonkey's database.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| The VM stays on after switching off | The guest does not react to the power button, for example in the installer. | Shut the guest down from inside. |
| Red message on start | QEMU could not start the machine. The message names the reason. | Fix the reason, such as a missing image. |
| The VM boots into the installer again | The image is still attached. | Eject ISO. |
| Edit and Delete are grey | The VM is running. | Stop it first. |
ssh does not connect |
SSH is not running in the guest yet, or the port is taken. | Set up SSH in the guest or pick another port. |
See also
Windows and other systems Free
Some systems WebDonkey deliberately does not download for you. Their vendors require you to accept their own terms before downloading, and that step is yours to take. That is why they are listed in the Not downloadable automatically section, with a link to the official page and a button to add the downloaded file.
Where to find it
Virtual machines page › Not downloadable automatically section, below the catalog. It is visible while the catalog is expanded.
It lists Windows 11, Windows Server, FreeBSD and openSUSE Leap.
How to do it
- Click Website next to the system you want. The vendor's download page opens in your browser.
- Download the image there and accept the vendor's terms.
- In WebDonkey, click Choose file… (or Import file… under Downloaded images) and pick the file.
- The image appears in the library. Create the VM as described in Create a VM.
For an image you downloaded yourself, WebDonkey reads operating system and architecture from the file name if it contains them. Otherwise you pick both in the dialog.
Windows on Apple silicon
Only a guest with the same architecture as your Mac runs hardware accelerated. On Apple silicon that is an ARM Windows. A Windows for Intel/AMD (x86_64) does start, but runs emulated and is correspondingly slow. The create dialog warns you then.
What happens in the background
Choose file… copies the image into the library at ~/Library/Application Support/WebDonkey/isos/. You can delete the original afterwards.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| The section is missing | The catalog is hidden. | Show catalog. |
| Operating system and architecture are not fixed | The file name does not state the architecture. | Pick both in the dialog. |
| Windows runs very slowly | An x86_64 image on Apple silicon runs emulated. | Use an ARM image. |