Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 36 ยท Providers and Plugins

Vagrant Plugins

Install and manage Vagrant plugins, use popular ones such as vagrant-hostmanager and vagrant-vbguest, require plugins in a Vagrantfile, and write a tiny plugin.

Vagrant is extensible. Providers, provisioners, commands, synced-folder types and even configuration options can all come from plugins, which are Ruby gems loaded by Vagrant at start-up. This lesson covers the plugin commands, a short list of widely used plugins, how to make a Vagrantfile insist on a plugin, and what a plugin looks like inside.

Managing plugins from the command line

TEXT
$ vagrant plugin install vagrant-hostmanager
Installing the 'vagrant-hostmanager' plugin. This can take a few minutes...
Installed the plugin 'vagrant-hostmanager (1.8.10)'!

$ vagrant plugin list
vagrant-hostmanager (1.8.10, global)
vagrant-vbguest (0.32.0, global)

$ vagrant plugin update                      # update every plugin
$ vagrant plugin update vagrant-vbguest      # update one
$ vagrant plugin uninstall vagrant-hostmanager
$ vagrant plugin repair                      # fix a broken plugin set
$ vagrant plugin expunge --reinstall         # last resort: remove all and reinstall

Plugins install into your user directory (~/.vagrant.d on Linux and macOS, %USERPROFILE%\.vagrant.d on Windows), not into the project. That means each teammate must install them, which is why requiring plugins in the Vagrantfile (below) is so useful.

Plugins are code that runs with your user's permissions each time you use Vagrant. Install only plugins you trust, from the official RubyGems index, and prefer ones that are actively maintained.

Plugin What it does
vagrant-hostmanager Keeps /etc/hosts in guests (and optionally the host) up to date with all machine names
vagrant-vbguest Installs or updates VirtualBox Guest Additions in the guest so shared folders keep working
vagrant-libvirt The libvirt/KVM provider
vagrant-vmware-desktop The VMware provider
vagrant-disksize Resizes the primary disk of a VirtualBox guest
vagrant-env Loads variables from a .env file into the Vagrantfile
vagrant-cachier Caches package downloads across machines (older, lightly maintained)
vagrant-proxyconf Configures HTTP proxies inside guests
vagrant-scp Adds vagrant scp to copy files to a machine
vagrant-reload Adds a provisioner that reboots the machine in the middle of provisioning

Maintenance status changes over time. Check the project's repository before depending on one in a team setup.

vagrant-hostmanager in practice

Ruby
Vagrant.configure("2") do |config|
  config.hostmanager.enabled = true
  config.hostmanager.manage_host = true      # also edit your own hosts file
  config.hostmanager.manage_guest = true
  config.hostmanager.include_offline = true

  config.vm.define "web" do |web|
    web.vm.hostname = "web.test"
    web.vm.network "private_network", ip: "192.168.56.10"
    web.hostmanager.aliases = %w[www.web.test]
  end
end

After vagrant up, http://web.test works from your browser. The plugin edits the hosts file, so it asks for administrator rights on your host. See networking between machines for the manual alternative.

vagrant-vbguest in practice

When the guest kernel and the Guest Additions version disagree, shared folders break. The plugin checks and rebuilds them at boot.

Ruby
config.vbguest.auto_update = true
config.vbguest.no_remote = true      # do not download ISOs; use the host's copy

Requiring plugins from the Vagrantfile

If a Vagrantfile uses config.hostmanager but a teammate has no such plugin, Vagrant stops with a confusing "unknown configuration section" error. The required_plugins mechanism installs what is needed automatically.

Ruby
required = %w[vagrant-hostmanager vagrant-vbguest]
missing  = required.reject { |p| Vagrant.has_plugin?(p) }

unless missing.empty?
  puts "Installing missing plugins: #{missing.join(', ')}"
  system("vagrant plugin install #{missing.join(' ')}") || abort("Plugin install failed")
  puts "Done. Run the command again."
  exit
end

Vagrant.has_plugin?("name") reports whether a plugin is loaded. Recent Vagrant versions also support a built-in declaration:

Ruby
Vagrant.configure("2") do |config|
  config.vagrant.plugins = ["vagrant-hostmanager", "vagrant-vbguest"]
end

With this, Vagrant offers to install any missing plugin on the first run. Using either form lets a new teammate go from git clone to a working machine with no wiki page of prerequisites.

What a plugin looks like inside

A plugin is a Ruby class that registers itself with Vagrant. The smallest useful one adds a new command.

Ruby
# vagrant-hello.rb
module VagrantPlugins
  module Hello
    class Plugin < Vagrant.plugin("2")
      name "hello"
      description "Adds the 'vagrant hello' command"

      command("hello") do
        Command
      end
    end

    class Command < Vagrant.plugin("2", :command)
      def execute
        @env.ui.info("Hello from #{@env.root_path}")
        0
      end
    end
  end
end

Packaged as a gem and installed, vagrant hello prints the project path. Real plugins hook into Vagrant's middleware stack: a list of steps run when a machine goes up or down, which plugins can insert themselves into.

A stand-in: a tiny plugin registry

The idea behind plugins is a registry that stores named extension points. This Ruby program models that idea and the "missing plugin" check from above. It is a stand-in; real Vagrant plugins use its Vagrant.plugin API.

Ruby A plugin registry in 30 lines

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The last two lines are exactly the pattern a Vagrantfile uses with Vagrant.has_plugin? to detect gaps before they cause errors.

Common mistakes

  • Not pinning versions for a team. A plugin update can break a Vagrantfile. Test updates before everyone installs them.
  • Mixing too many plugins. Each one is an extra thing to break after a Vagrant upgrade.
  • Forgetting that plugins are per user, not per project. Always declare them in the Vagrantfile.
  • Plugin build failures on Linux. Native extensions need compilers and headers (build-essential, ruby-dev).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where are Vagrant plugins installed?

    Plugins are installed per user, so every teammate needs them; declare them in the Vagrantfile.
  2. 2. What does Vagrant.has_plugin?("vagrant-hostmanager") return?

    It is a boolean check you can use to fail early or install missing plugins.
  3. 3. What problem does vagrant-vbguest solve?

    It installs or updates the Guest Additions in the guest at boot.
  4. 4. Why is it risky to install an unknown plugin?

    A plugin is arbitrary code that runs every time Vagrant starts.

Summary

  • Install and manage plugins with vagrant plugin install|list|update|uninstall|repair.
  • Plugins are per user; declare them in the Vagrantfile so teammates get them automatically.
  • Useful ones: hostmanager (names), vbguest (shared folders), libvirt and VMware (providers), disksize, env.
  • A plugin is a Ruby class registered with Vagrant.plugin("2"); trust and pin what you install.

Next: Sharing a Vagrantfile in Git