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

      Cannot connect to the VM on macOS

      On macOS 15 or later, minikube start can fail while waiting for the SSH server, even though the VM boots and gets an IP address. For example, with the vfkit driver:

      minikube start --driver vfkit

      😄  minikube v1.39.0 on Darwin 26.6.2 (arm64)
✨  Using the vfkit driver based on user configuration
🌐  Automatically selected the vmnet-shared network
👍  Starting "minikube" primary control-plane node in "minikube" cluster
🔥  Creating vfkit VM (CPUs=2, Memory=6144MB, Disk=20000MB) ...
🔥  Deleting "minikube" in vfkit ...
🤦  StartHost failed, but will try again: creating host: create: creating: timeout waiting for SSH server "192.168.64.3:22"
🔥  Creating vfkit VM (CPUs=2, Memory=6144MB, Disk=20000MB) ...
😿  Failed to start vfkit VM. Running "minikube delete" may fix it: creating host: create: creating: timeout waiting for SSH server "192.168.64.3:22"

❌  Exiting due to GUEST_PROVISION: error provisioning guest: Failed to start host: creating host: create: creating: timeout waiting for SSH server "192.168.64.3:22"

      Starting with --alsologtostderr -v=7 shows that the VM gets an IP address from DHCP, but every connection to it fails immediately:

      libmachine: IP: 192.168.64.3
libmachine: Waiting until SSH server "192.168.64.3:22" is accessible
libmachine: Dialing to SSH server "192.168.64.3:22"
libmachine: Failed to dial: dial tcp 192.168.64.3:22: connect: no route to host

      macOS 15 introduced a privacy control for the local network. minikube connects directly to the IP address of the VM, which is on a local network, so you must allow the application you run minikube from to access the local network.

      Commands you run in Terminal.app always have local network access, and the Local Network entry for Terminal.app has no effect. Every other terminal needs the permission, including third-party terminals such as iTerm2 or Ghostty and the terminals embedded in editors and IDEs such as Visual Studio Code.

      If you clicked Don’t Allow when macOS asked for this permission, macOS does not ask again. The permission can be off even though you do not remember denying it, possibly from long before you installed minikube.

      To fix this:

      1. Choose Apple menu > System Settings, then click Privacy & Security in the sidebar.
      2. Click Local Network.
      3. Find the terminal application or IDE you run minikube from in the list, and turn it on.

      Then start the cluster again.

      For more information, see Control access to your local network on Mac.


      Last modified September 16, 2026: docs: Add troubleshooting for macOS local network permission (7b8d63585)