vfkit
Overview
VFKit is an open-source program for macOS virtualization, optimized for lightweight virtual machines and container deployment.
Requirements
- Requires macOS 14 or later.
- Requires minikube version 1.36.0 or later.
Networking
The vfkit driver has two networking options: nat and vmnet-shared.
The nat network is always available, but it does not provide access
between minikube clusters. To access other clusters or run multi-node
cluster, you need the vmnet-shared network. The vmnet-shared network
requires vmnet-helper, see
installation instructions below.
Requirements
-
Requires vmnet-helper.
Install vmnet-helper
On macOS 26 or later, install vmnet-helper using Homebrew:
brew tap nirs/vmnet-helper
brew trust nirs/vmnet-helper
brew install vmnet-helper
On macOS 15 or earlier, install the latest version using the install script:
curl -fsSL https://github.com/minikube-machine/vmnet-helper/releases/latest/download/install.sh | bash
The command downloads the latest release from GitHub and installs it to
/opt/vmnet-helper, and configures a sudoers rule to allow running
vmnet-helper without a password.
Grant permission to run vmnet-helper manually on macOS 15 or earlier
On macOS 15 or earlier, vmnet-helper must run as root to create a vmnet interface. To let users in the staff group run it without a password, install the default sudoers rule. The install script offers to add this automatically; if you declined, run the command below manually:
sudo install -m 0640 /opt/vmnet-helper/share/doc/vmnet-helper/sudoers.d/vmnet-helper /etc/sudoers.d/
You can change the sudoers configuration to allow access to specific users or other groups.
IMPORTANT: On macOS 15 or earlier, the vmnet-helper executable and the directory where it is installed must be owned by root and may not be modifiable by unprivileged users.
Usage
minikube start --driver vfkit --network vmnet-shared
Usage
minikube start --driver vfkit [--network nat]
The nat network is used by default if the --network option is not
specified.
Issues
Other
Troubleshooting
Run with logs
Run minikube start --driver vfkit --alsologtostderr -v=7 to debug crashes
Upgrade VFKit
brew update
brew upgrade vfkit
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:
- Choose Apple menu > System Settings, then click Privacy & Security in the sidebar.
- Click Local Network.
- 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.
Troubleshooting the vmnet-shared network
Check for errors in vmnet-helper log:
$MINIKUBE_HOME/.minikube/machines/MACHINE-NAME/vmnet-helper.log
Check that the vmnet-helper process is running:
ps au | grep vmnet-helper | grep -v grep
If the helper is not running restart the minikube cluster.
For help with vmnet-helper please use the discussions.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.