qemu

QEMU driver

Overview

The qemu driver uses QEMU (system) for VM creation.

https://www.qemu.org/

Usage

To start minikube with the qemu driver:

minikube start --driver=qemu

Special features

minikube start supports some qemu specific flags:

  • --qemu-firmware-path: The path to the firmware image to be used.
    • Note: while the flag should override the config, if the flag does not take effect try running minikube delete.
    • MacPorts: if you are installing minikube and qemu via MacPorts on a Mac with M1, use the following flag: --qemu-firmware-path=/opt/local/share/qemu/edk2-aarch64-code.fd

Networking

The QEMU driver has two networking options: socket_vmnet and builtin. socket_vmnet will give you full minikube networking functionality, such as the service and tunnel commands. On the other hand, the builtin network is not a dedicated network and therefore commands such as service and tunnel are not available. socket_vmnet can be installed via brew or from source (instructions below).

    Requirements

    Requires macOS 10.15 or later and socket_vmnet.

    Install socket_vmnet via brew

    brew install socket_vmnet
HOMEBREW=$(which brew) && sudo ${HOMEBREW} services start socket_vmnet

    Install socket_vmnet from source (requires Go)

    git clone https://github.com/lima-vm/socket_vmnet.git && cd socket_vmnet
sudo make install

    Usage

    minikube start --driver qemu --network socket_vmnet

    Usage

    minikube start --driver qemu --network builtin

    Known Issues

      /var/db/dhcpd_leases errors

      If you’re seeing errors related to /var/db/dhcpd_leases your firewall is likely blocking the bootpd process.

      Run the following to unblock bootpd from the macOS builtin firewall:

      sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/libexec/bootpd
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblock /usr/libexec/bootpd

      Start stuck on corp machine or with custom DNS

      When using the builtin network (default) the guest uses only the first nameserver entry in the hosts /etc/resolv.conf for DNS lookup. If your first nameserver entry is a corporate/internal DNS it’s likely it will cause an issue. If you see the warning ❗ This VM is having trouble accessing https://registry.k8s.io on minikube start you are likely being affected by this. This may prevent your cluster from starting entirely and you won’t be able to pull remote images. More details can be found at: #15021

      Workarounds:

      1. If possible, reorder your /etc/resolv.conf to have a general nameserver entry first (eg. 8.8.8.8) and reboot your machine.
      2. Use --network=socket_vmnet

      Full list of open ‘qemu’ driver issues

      Troubleshooting

      • Run minikube start --alsologtostderr -v=4 to debug crashes

      Last modified May 15, 2025: Update qemu.md docs for homebrew/services decommission (#20685) (b0a069508)