vagrant-vsphere lets Vagrant clone and manage VMs on vSphere

A Vagrant provider for an existing vSphere estate

vagrant-vsphere is a Vagrant 1.6.4 or later plugin that adds a vSphere provider to Vagrant, allowing Vagrant to control and provision machines using VMware. The audience is implied by the design. This is not a tool for spinning up a hypervisor or for local development; it is a way to make a Vagrantfile drive machines inside an organisation's existing vSphere infrastructure. New machines are created from virtual machines or templates which must be configured prior to using this provider, so the workflow presumes a template library that someone else maintains. Underneath, the provider is built on top of the RbVmomi Ruby interface to the vSphere API, which is the detail that decides what is easy and what is hard about it. Talking to vSphere through a maintained Ruby client means the provider inherits real API coverage, but it also means the provider's behaviour is bounded by what RbVmomi exposes and by the shape of the vSphere data model, which is folder and resource pool heavy rather than machine-name heavy.

Installing the plugin and the Nokogiri constraint

Installation is the standard Vagrant plugin method.

vagrant plugin install vagrant-vsphere

That pulls the plugin from RubyGems.org. The alternative is to clone the repository and build the source with gem build vSphere.gemspec, then run the plugin install command from the build directory. There is a real installation caveat that the documentation spells out. The requirements for Nokogiri must be installed before the plugin can be installed, with a link to the Nokogiri tutorial for detailed instructions, and the plugin forces use of Nokogiri ~> 1.5 to prevent conflicts with older versions of system libraries, specifically zlib. That pinned constraint is worth understanding on a modern workstation, because a system that ships a newer libxml2 and libxslt is exactly the case where the conflict the pin was designed to avoid reappears. The stated requirements for the whole stack are Vagrant 1.6.4+, VMware with vSphere API, Ruby 1.9+, and libxml2, libxml2-dev, libxslt and libxslt-dev. The Ruby 1.9 floor is clearly historic, while the current version is 1.15.0, published on RubyGems.org and tagged v1.15.0 on 2026-08-12.

Building a dummy box and writing the Vagrantfile

After installing the plugin you must create a vSphere box, and the repository ships an example_box directory with a metadata.json file that can be used to create a dummy box.

tar cvzf dummy.box ./metadata.json

That box can be installed using the standard Vagrant methods or specified in the Vagrantfile. The Vagrantfile itself is short, and its shape tells you how the provider is configured.

Vagrant.configure("2") do |config|
  config.vm.box = 'dummy'
  config.vm.box_url = './example_box/dummy.box'

  config.vm.provider :vsphere do |vsphere|
    vsphere.host = 'HOST NAME OF YOUR VSPHERE INSTANCE'
    vsphere.compute_resource_name = 'YOUR COMPUTE RESOURCE'
    vsphere.resource_pool_name = 'YOUR RESOURCE POOL'
    vsphere.template_name = '/PATH/TO/YOUR VM TEMPLATE'
    vsphere.name = 'NEW VM NAME'
    vsphere.user = 'YOUR VMWARE USER'
    vsphere.password = 'YOUR VMWARE PASSWORD'
  end
end

Then the machine is created with vagrant up --provider=vsphere. The bulk of this configuration can also be included as part of a custom box, and the documentation points at the Vagrant box documentation and at the AWS provider's example_box for a reference implementation. The credentials in the file are placeholders, and the password setting accepts :ask to be prompted on each invocation, which is the safer default for anything that ends up in version control.

The settings that control where the VM lands

The provider exposes a long list of settings, and reading them tells you how much of the vSphere data model it models. Beyond the obvious host, user and password, the placement settings are the interesting ones. data_center_name is optional, and if it is not specified the first datacenter found will be used, which is a convenience that becomes a surprise in an environment with several datacenters. compute_resource_name is required if cloning from a template, and it names the host or cluster containing the resource pool. resource_pool_name points at the pool, and if it is left out while cloning from a template the root resource pool is used. template_name is the VM or VM template to clone, including the full folder path, and clone_from_vm is the alternative that uses an existing virtual machine as the source. vm_base_path is optional and sets the folder where the new VM is created, defaulting to the template's parent folder. name is optional and auto-generated if missing, data_store_name selects the datastore, and customization_spec_name applies a guest customization spec to the new VM. Two settings are worth calling out for behaviour. linked_clone links the cloned VM to the parent to share virtual disks, which is fast and space efficient but ties the lifetime of the child to the parent. real_nic_ip forces the ssh address to be acquired from the list of VM adapters on the host and filtered for a single legitimate address, which matters in environments with several NICs where the default selection picks the wrong one.

Networking, hardware sizing and guestinfo variables

The remaining settings cover hardware and the guest side of the VM. vlan connects the first NIC to a specific VLAN, and addressType configures the address type of the vSphere virtual ethernet card. The sizing options are memory_mb for the amount of memory in MB, cpu_count for the number of CPUs, and the reservation pair cpu_reservation in MHz and mem_reservation in MB, which are the values you set when a cluster is configured for admission control and the VM needs a guaranteed share. The mac setting sets the MAC address of the new VM, which is what you need when the VM has to appear with a stable identity to a licence server or a firewall rule. Two settings reach inside the guest. extra_config is a hash of extra configuration values added to the VM during creation, of the form {'guestinfo.some.variable' => 'somevalue'}, where the key must start with guestinfo., and a VM with VMware Tools installed can read those values with the vmtoolsd command, for example vmtoolsd --cmd 'info-get guestinfo.some.variable'. That is the supported channel for passing configuration into a guest that you did not build the image for. custom_attribute adds a vSphere custom attribute to the VM upon creation, taking a key and value pair, and it may be called multiple times to set different attributes. notes attaches arbitrary notes, and proxy_host and proxy_port cover connecting to vSphere through a proxy.

Five commands, and provisioning through the standard set

The supported command list is short and worth knowing before you design a workflow. Currently the only implemented actions are up, halt, reload, destroy and ssh. Everything else in the Vagrant vocabulary, including the box commands and the provider-specific extras, is not implemented. Provisioning is the exception, since up supports provisioning of the new VM with the standard Vagrant provisioners, so shell scripts, Ansible and the other built-in provisioners work as usual against a vSphere VM. That combination, a small command surface with the full standard provisioner set, is a reasonable shape for the tool's purpose. It is also the clearest statement of the boundary: the provider handles machine lifecycle and placement, and it delegates everything about what runs inside the machine to Vagrant itself. If your workflow depends on snapshot management, on storage vMotion, or on any other operation beyond bring up, halt, reload, destroy and ssh, you will need the vSphere API directly rather than this provider.

Maintenance and licence, stated plainly by the project

The project is explicit about its support posture. The repository is not actively supported by NSIDC, but issue submissions and pull requests are welcome so that the community can keep contributing, and the documentation points to the LICENSE file for details on permissions and warranties, with [email protected] given as a contact. The licence field is recorded as a custom one that GitHub cannot classify, so the LICENSE file is the authority and it is worth reading before you embed the plugin in a build pipeline. The release history shows the shape of the maintenance. Version 1.15.0 was tagged on 2026-08-12, but the two preceding releases, 1.13.5 and 1.14.0, are both dated 2022-08-02, which means there was a four year gap followed by a jump to 1.15.0 in 2026. The last push to the repository was on 2026-08-13. The repository itself is a conventional Ruby gem layout with a vSphere.gemspec, a Rakefile, a .ruby-version, rubocop configuration, a locales directory and a spec directory, plus a .bumpversion.cfg for version bumping and DEVELOPMENT.md for contributor guidance. The jump from 1.14 to 1.15 after four silent years is the fact to weigh when you decide how much to depend on it.

Editorial conclusion

Adopt vagrant-vsphere if your team already runs VMware vSphere and wants test machines created from templates through the same Vagrantfile workflow you use for other providers. Do not adopt it for a greenfield lab, since the project states it is not actively supported by NSIDC, and do not adopt it if you need provisioner features beyond the standard Vagrant set, since the only implemented actions are up, halt, reload, destroy and ssh. Verify two things before you rely on it: that your vSphere API endpoint and credentials work, including whether you need to disable SSL verification through the insecure setting, and that the machine template you clone from already exists and is configured, since the provider clones from virtual machines or templates which must be configured prior to use. The practical first step is vagrant plugin install vagrant-vsphere, then vagrant up --provider=vsphere with a template_name pointing at a template that already exists.

Frequently asked questions

Official sources

1. Issues
2. nsidc/vagrant-vsphere on GitHub
3. README
4. Releases