Buy

Virtual machines

Free

The 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

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

  1. Open Virtual machines.
  2. Under This command will run, the card shows the command brew install qemu.
  3. Click Install engine. The installation takes roughly 1 GB and a few minutes.
  4. While it installs, a bar runs and below it the latest line of the output.
  5. 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

  1. 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.
  2. Search with Search… if needed. The catalog is grouped into Desktop and Server & minimal.
  3. If there are several versions, pick one in the selector (Version). The newest is preselected.
  4. Click Download. A bar shows the progress with the downloaded and total size. Cancel stops the download.
  5. 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

  1. Under Downloaded images, click Import file….
  2. Pick the file (.iso, .img or .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

  1. Click Remove (trash can) in the image's row.
  2. 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

  1. Click New VM.
  2. Enter a Name, for example "Ubuntu Server".
  3. 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.
  4. 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.
  5. Set the hardware: Memory, CPU cores, Disk size.
  6. Optional: SSH port forward and Window size.
  7. 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 disk disk.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

  1. Open the create dialog or Edit. The VM has to be stopped for editing.
  2. Pick one of the sizes or Custom.
  3. Tick Open in fullscreen if you like.
  4. 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

  1. Turn on the machine's switch in the Status column. The VM boots and opens its own window, where you operate the guest system.
  2. 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.

  1. Stop the VM.
  2. In the row, click Eject ISO after ISO and the image's name.
  3. Confirm Eject ISO?.

The image file is kept, and you can attach it again later with Edit.

Notes

  1. Click the note icon (Notes).
  2. Write in the field what the VM is for, which login it was set up with and what still needs doing inside it.
  3. Click Save.

Notes can be edited while the VM runs too. A machine with a note shows the icon highlighted.

Delete

  1. Stop the VM.
  2. Click the trash can (Delete).
  3. 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

  1. Click Website next to the system you want. The vendor's download page opens in your browser.
  2. Download the image there and accept the vendor's terms.
  3. In WebDonkey, click Choose file… (or Import file… under Downloaded images) and pick the file.
  4. 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.

See also

Cookie preferences

This website uses cookies to ensure the best experience possible. Your choice applies to webdonkey.io and the shop at shop.webdonkey.io. More information...

Technically required

Cookies required for this website to function:

Always on
WebDonkey
WebDonkey
Provider: BuI Hinsche GmbH, Neumarkt 7, 06712 Zeitz, Germany
Purpose: Your consent, colour scheme and language for website and shop, price switches; with wd_debug in the address, the measurement events in the developer console for troubleshooting
Cookies and storage: Cookie wd_consent on .webdonkey.io, shared with shop.webdonkey.io (12 months); cookies wd_theme and wd_lang on .webdonkey.io, shared with shop.webdonkey.io, only when you switch colour scheme or language yourself (365 days); localStorage wd:consent, wd:theme, wd:lang; sessionStorage wd:acc, wd:term, wd:debug (only with wd_debug in the address; until the tab closes)

Statistics

Shows us which pages and products people look at on webdonkey.io and in the shop, where visitors come from and how they get to a purchase (with order number, amount and products, without name or email address). Provider: Google. Transfer to the USA possible (EU-US Data Privacy Framework). Your choice applies to webdonkey.io and the shop together.

Google Tag Manager, Google Analytics 4
Google Tag Manager
Provider: Google Ireland Limited, Gordon House, Barrow Street, Dublin 4, Ireland
Purpose: Loads the services you agreed to, here and in the shop. Sets no cookies of its own.
Cookies and storage: none
Privacy policy
Google Analytics 4
Provider: Google Ireland Limited, Gordon House, Barrow Street, Dublin 4, Ireland
Purpose: Usage statistics: page views, clicks, scroll depth, sources, devices, load times; in the shop also basket, checkout, purchases, registration and sign-in
Cookies and storage: _ga, _ga_<ID> (2 years)
Privacy policy

Marketing

Measures whether our ads on Facebook, Instagram and TikTok lead to visits and downloads on webdonkey.io and to registrations and purchases in the shop, and builds audiences for ads. Providers: Meta and TikTok, with whom we are jointly responsible for this. With this consent Google may also set advertising cookies (_gcl_…). Transfer to the USA and other countries outside the EU possible. Your choice applies to webdonkey.io and the shop together.

Google Tag Manager, Meta Pixel (Facebook, Instagram), TikTok Pixel
Google Tag Manager
Provider: Google Ireland Limited, Gordon House, Barrow Street, Dublin 4, Ireland
Purpose: Loads the services you agreed to, here and in the shop. Sets no cookies of its own.
Cookies and storage: none
Privacy policy
Meta Pixel (Facebook, Instagram)
Provider: Meta Platforms Ireland Limited, Merrion Road, Dublin 4, D04 X2K5, Ireland
Purpose: Ad measurement and target groups on Facebook and Instagram, also in the shop (basket, checkout, purchases, registration)
Cookies and storage: _fbp (3 months), _fbc (3 months, only if you arrive through an ad), fr on facebook.com (3 months)
Privacy policy
TikTok Pixel
Provider: TikTok Technology Limited, 10 Earlsfort Terrace, Dublin, D02 T380, Ireland
Purpose: Ad measurement and target groups on TikTok, also in the shop (basket, checkout, purchases, registration)
Cookies and storage: _ttp, _tt_enable_cookie (13 months)
Privacy policy