Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
V

vagrant-qemu

> 编程语言
Open source

Use Vagrant to manage machines using QEMU. Test with Apple Silicon / M1 and CentOS aarch64 image

506 stars0 likes3 views
WebsiteGitHub

About

Use Vagrant to manage machines using QEMU. Test with Apple Silicon / M1 and CentOS aarch64 image

Vagrant QEMU Provider

This is a Vagrant plugin that adds a simple QEMU provider to Vagrant, allowing Vagrant to control and provision machines using QEMU.

Notes: test with Apple Silicon / M1 and CentOS / Ubuntu aarch64 image

Compatible with

Tested:

  • MacOS >= 12.4
  • QEMU >= 7.0.0
  • CentOS (centos-7-aarch64-2009-4K)
  • Ubuntu (see Wiki for detais)
  • Debian buster64 on x86_64 (see Wiki for detais)

Others:

  • (MacOS = 7.0.0) : update OS, or use QEMU 6.x
  • QEMU 6.x: use following config:
    config.vm.provider "qemu" do |qe|
      qe.machine = "virt,accel=hvf,highmem=off"
      qe.cpu = "cortex-a72"
    end

Features

  • Import from a Libvirt vagrant box or qcow2 image
    • To use box for Paralles or VMware Fusion, see Wiki for details
    • Libvirt box v2 format support is experimental
  • Start VM without GUI
  • SSH into VM
  • Provision the instances with any built-in Vagrant provisioner
  • Synced folder support via SMB
  • Basic operation: up, ssh, halt, destroy
  • Basic suport to forwarded ports, see vagrant doc for details
  • Support Cloud-init, see vagrant doc for details
  • Support Disks, see vagrant doc for details
  • Advanced networking (opt-in): dual-NIC with private_network support via QEMU native vmnet (macOS), TAP (Linux), or a socket netdev — multicast (Linux/Windows) or point-to-point listen/connect (no root, works on macOS)

Usage

Make sure QEMU is installed, if not:

bash
brew install qemu

Install plugin:

vagrant plugin install vagrant-qemu

Prepare a Vagrantfile, see Example, and start:

vagrant up --provider qemu

Notes:

  • may need password to setup SMB on Mac, see vagrant doc for details
  • need username/password to access shared folder

Box format

Same as vagrant-libvirt version-1:

  • qcow2 image file named box.img
  • metadata.json file describing box image (provider, virtual_size, format)
  • Vagrantfile that does default settings

Configuration

Options

This provider exposes a few provider-specific configuration options:

  • basic
    • ssh_port - The SSH port number used to access VM, default: 50022
    • arch - The architecture of VM, default: auto-detected from the host (aarch64 on Apple Silicon, x86_64 on Intel)
    • machine - The machine type of VM, default: auto-detected from host OS + arch. For native virtualization (guest arch == host arch): virt,highmem=on,accel=hvf (arm64) / q35,accel=hvf (x86_64) on macOS, accel=kvm on Linux, accel=whpx on Windows. When emulating a non-host arch it uses accel=tcg.
    • cpu - The cpu model of VM, default: host for native virtualization, max when emulating a non-host arch
    • smp - The smp setting (Simulate an SMP system with n CPUs) of VM, default: 2
    • memory - The memory setting of VM, default: 4G
    • disk_resize - The target disk size of the primary disk, requires resizing of filesystem inside of VM, default: nil.
  • debug/expert
    • ssh_host - The SSH IP used to access VM, default: 127.0.0.1
    • ssh_auto_correct - Auto correct port collisions for ssh port, default: false
    • net_device - The network device, default: auto-detected — virtio-net-device (arm64 virt) or virtio-net-pci (x86_64 q35)
    • drive_interface - The interface type for the main drive, default virtio
    • image_path - The path (or array of paths) to qcow2 image for box-less VM, default is nil value
    • qemu_bin - Path to an alternative QEMU binary, default: autodetected
    • qemu_dir - The path to QEMU's data/firmware dir. Default resolution order: ENV["QEMU_DIR"] → ${HOMEBREW_PREFIX}/share/qemu → per-host default (/opt/homebrew/share/qemu on Apple Silicon, /usr/local/share/qemu on Intel macOS, /usr/share/qemu on Linux). Only consumed for aarch64 firmware; ignored (and not validated) for x86_64.
    • extra_qemu_args - The raw list of additional arguments to pass to QEMU. Use with extreme caution. (see "Force Multicore" below as example)
    • extra_netdev_args - extra, comma-separated arguments to pass to the -netdev parameter. Use with caution. (see "Force Local IP" below as example)
    • extra_drive_args - Add optional extra arguments to each drive attached, default: []
    • control_port - The port number used to control vm from vagrant, default is nil value. (nil means use unix socket)
    • debug_port - The port number used to export serial port of the vm for debug, default is nil value. (nil means use unix socket, see "Debug" below for details)
    • no_daemonize - Disable the "daemonize" mode of QEMU, default is false. (see "Windows host" below as example)
    • firmware_format - The format of aarch64 firmware images (edk2-aarch64-code.fd and edk2-arm-vars.fd) loaded from qemu_dir, default: raw
    • other_default - The other default arguments used by this plugin, default: %W(-parallel null -monitor none -display none -vga none)
    • extra_image_opts - Options passed via -o to qemu-img when the base qcow2 images are created, default: []
    • graceful_timeout - Seconds to wait at each vagrant halt stage before escalating, default: 60. Halt sends ACPI system_powerdown, waits up to this long, then sends QEMU's quit monitor command (a clean shutdown that flushes and closes the disk images), waits again, and finally SIGKILLs QEMU as a last resort — so halt still completes even when the guest was already halted from inside (e.g. sudo systemctl halt), where system_powerdown is a no-op
  • advanced networking (requires advanced_network = true)
    • advanced_network - Enable dual-NIC advanced networking with private_network support, default: false
    • net_mode - Network backend: :auto (detect by platform), :vmnet_shared, :vmnet_host, :vmnet_bridged (macOS, sudo), :socket_vmnet (macOS, no sudo — via the socket_vmnet daemon), :tap (Linux), :socket (QEMU socket netdev — multicast or point-to-point, see socket_opts), default: :auto
    • vmnet_interface - Physical interface for vmnet-bridged mode, default: en0
    • tap_device - TAP device name for Linux tap backend, default: nil (uses tap0)
    • mcast_addr - Convenience shortcut for the :socket backend's multicast address, default: nil (uses 230.0.0.1:1234)
    • socket_opts - Raw options for the :socket netdev, emitted verbatim as -netdev socket,id=netN,. You pick the mode: "mcast=230.0.0.1:1234" (multicast, N-way), "listen=:1234" / "connect=127.0.0.1:1234" (point-to-point; you decide which VM listens and which connects — the no-root, macOS-friendly path). Overrides mcast_addr. Default: nil (falls back to multicast)
    • socket_vmnet_socket - Path to the socket_vmnet daemon's unix socket, used by the :socket_vmnet backend, default: /var/run/socket_vmnet (HOMEBREW_PREFIX env, else /opt/homebrew on Apple Silicon, /usr/local on Intel)
    • socket_vmnet_client - Path to the socket_vmnet_client wrapper, used only on QEMU older than 7.2 (which lacks the native stream netdev), default: /opt/socket_vmnet/bin/socket_vmnet_client

Usage

These can be set like typical provider-specific configuration:

# Basic Vagrant config (API version 2)
Vagrant.configure(2) do |config|
  # ... other stuff

  config.vm.provider "qemu" do |qe|
    qe.memory = "8G"
  end
end

With nil value

To be able to custom the result qemu command deeply, you can set some config options to nil value to skip related qemu arguments.

  • machine: skip -machine xxx
  • cpu: skip -cpu xxx
  • smp: skip -smp xxx
  • memory: skip -m xxx
  • net_device: skip all network related arguments:
    • -device xxx,netdev=net0
    • -netdev user,id=net0,xxx
    • NOTES: there will be no network, ssh won't work
  • drive_interface: skip drive for the main image, -drive if=xxx,xxx
  • firmware_format: skip firmware setup for aarch64, -drive if=pflash,xxx

With other_default = [], all default arguments will be skipped.

Example

  1. Try with a sample box
vagrant init ppggff/centos-7-aarch64-2009-4K
vagrant up --provider qemu
  1. With a local box
# Basic Vagrant config (API version 2)
Vagrant.configure(2) do |config|
  config.vm.box = "test-box"
  config.vm.box_url = "file:///Users/xxx/test.box"
  config.vm.box_check_update = false
end
  1. With a local qcow2
# Basic Vagrant config (API version 2)
Vagrant.configure(2) do |config|
  config.vm.provider "qemu" do |qe, override|
    override.ssh.username = "xxx"
    override.ssh.password = "vagrant"

    qe.image_path = "/Users/xxx/test.qcow2"
  end
end
  1. Work with a x86_64 box (basic config)

On an Intel Mac (or Linux x86_64 host) these defaults are now auto-detected, so a plain config.vm.box = "..." with no provider overrides is usually enough. The explicit settings below are only needed to emulate x86_64 on an Apple Silicon host (cross-arch → TCG):

Vagrant.configure(2) do |config|
  config.vm.box = "centos/7"

  config.vm.provider "qemu" do |qe|
    qe.arch = "x86_64"
    qe.machine = "q35"
    qe.cpu = "qemu64"
    qe.net_device = "virtio-net-pci"
  end
end
  1. Forwarded ports
# Basic Vagrant config (API version 2)
Vagrant.configure(2) do |config|
  # ... other stuff

  config.vm.network "forwarded_port", guest: 80, host: 8080
end
  1. Force Multicore (x86)

Thanks to taraszka for providing this config.

Vagrant.configure("2") do |config|
  config.vm.box = "centos/7"

  config.vm.provider "qemu" do |qe|
    qe.arch = "x86_64"
    qe.machine = "q35"
    qe.cpu = "max"
    qe.smp = "cpus=2,sockets=1,cores=2,threads=1"
    qe.net_device = "virtio-net-pci"
    qe.extra_qemu_args = %w(-accel tcg,thread=multi,tb-size=512)
    qe.qemu_dir = "/usr/local/share/qemu"
  end
end
  1. Force Local IP
Vagrant.configure("2") do |config|
  config.vm.box = "debian/bullseye64"

  config.vm.provider "qemu" do |qe|
    qe.extra_netdev_args = "net=192.168.51.0/24,dhcpstart=192.168.51.10"
  end
end
  1. Windows host

Windows version QEMU doesn't support daemonize mode and unix socket

Vagrant.configure("2") do |config|
  # ... other stuff

  config.vm.provider "qemu" do |qe|
    qe.no_daemonize = true
    qe.control_port = 33333
    qe.debug_port = 33334
  end
end
  1. Auto port collisions for ssh port (multiple machine)
Vagrant.configure("2") do |config|

  config.vm.define "vm1" do |c|
    c.vm.box = "ppggff/centos-7-aarch64-2009-4K"
    c.vm.provider "qemu" do |qe|
      qe.memory = "2G"
      qe.ssh_auto_correct = true
    end
    c.vm.synced_folder ".", "/vagrant", disabled: true
  end

  config.vm.define "vm2" do |c|
    c.vm.box = "ppggff/centos-7-aarch64-2009-4K"
    c.vm.provider "qemu" do |qe|
      qe.memory = "2G"
      qe.ssh_auto_correct = true
    end
    c.vm.synced_folder ".", "/vagrant", disabled: true
  end

end
  1. Use socket_vmnet to communicate between machines

Thanks example from @Leandros.

See pr#73 for details.

  1. Improved VM I/O performance

When creating the disks that are attached, each disk is an id assign in order they appear in the Vagrantfile. The primary disk has the id of disk0.

ruby
Vagrant.configure("2") do |config|
  # ... other stuff

  config.vm.provider "qemu" do |qe|
    # Use a `none` drive interface.
    qe.drive_interface = "none"
    qe.extra_drive_args = "cache=none,aio=threads"

    # To improve I/O performance, create a separate I/O thread.
    # We refer to the primary disk as `disk0`.

Issues· 30 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Ruby

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言