Skip to main content
Mapagam

Working with Vagrant Plugins

1. Installing Plugin

Command Description Notes
vagrant plugin install <plugin-name> Installs a Vagrant plugin from the default registry Can install plugins from local files or Git repositories
vagrant plugin install <plugin-name> --plugin-version <version> Installs a specific version of the plugin Useful for ensuring consistent environments across teams
vagrant plugin install <plugin-name> --plugin-source <source-url> Installs a plugin from a custom source (e.g., local file or Git repo) Allows installation of plugins not available in the default registry

Example: Installing a Plugin

vagrant plugin install vagrant-vsphere

Example: Installing a Specific Version

vagrant plugin install vagrant-vsphere --plugin-version 1.2.3
Note: Vagrant plugins are installed globally and can be used across all Vagrant environments on the system.

2. Listing Installed Plugins

Command Description Notes
vagrant plugin list List all installed plugins Shows plugin name, version, and installation path
vagrant plugin list --details List installed plugins with detailed information Includes plugin description, author, and homepage URL

Example: Listing installed plugins

$ vagrant plugin list
vagrant-vsphere (2.7.0)
  - Version: 2.7.0
  - Path: /home/user/.vagrant.d/plugins/gems/2.7.0/gems/vagrant-vsphere-2.7.0

vagrant-disksize (1.0.2)
  - Version: 1.0.2
  - Path: /home/user/.vagrant.d/plugins/gems/2.7.0/gems/vagrant-disksize-1.0.2

3. Updating Plugin

Command Description Notes
vagrant plugin update Updates all installed plugins to their latest versions Uses the latest version available from the plugin source
vagrant plugin update <plugin-name> Updates a specific plugin to its latest version Useful when only one plugin needs updating

Example: Update a specific plugin

vagrant plugin update vagrant-vboxmanage
Note: The update command will attempt to resolve dependencies and may install newer versions of dependent plugins.

4. Uninstalling Plugin

Command Description Notes
vagrant plugin uninstall <plugin-name> Uninstalls a specific Vagrant plugin Removes the plugin and all its dependencies from the system

Example: Uninstalling a Plugin

vagrant plugin uninstall vagrant-vsphere
Note: Ensure the plugin is not in use by any active Vagrant environments before uninstalling.

5. Installing Specific Version

Command Description Example
vagrant plugin install Install a specific version of a Vagrant plugin vagrant plugin install vagrant-vsphere --plugin-version 1.7.0

Example: Installing a specific version of a plugin

vagrant plugin install vagrant-vsphere --plugin-version 1.7.0
Note: Ensure the version you specify is compatible with your Vagrant version.

6. Using Plugin Sources

Source Type Description Usage Example Notes
vagrant plugin sources List all configured plugin sources vagrant plugin sources Shows all configured sources in order of priority
vagrant plugin source add Add a new plugin source vagrant plugin source add https://rubygems.org Can be a RubyGems or custom source URL
vagrant plugin source remove Remove a configured plugin source vagrant plugin source remove https://rubygems.org Removes the source from the list of available sources
vagrant plugin source list Display all sources with details vagrant plugin source list Shows the priority and URL of each source
Note: Plugin sources are used to resolve and install Vagrant plugins from different RubyGems repositories or custom endpoints.

7. Checking Plugin License

Command Description Notes
vagrant plugin license Displays the license information for a specific plugin. Requires the plugin name as an argument.

Example: Check plugin license

vagrant plugin license my-plugin
Note: The license information is fetched from the plugin's metadata or its associated repository.

8. Repairing Plugin Installation

Issue Solution Notes
Plugin fails to load vagrant plugin repair <plugin-name> Attempts to reinstall and fix plugin dependencies
Plugin version mismatch 
vagrant plugin uninstall <plugin-name>
vagrant plugin install <plugin-name>
 Reinstall the plugin to match current Vagrant version
Corrupted plugin files vagrant plugin expunge <plugin-name> Removes all traces and reinstalls plugin

Example: Repairing a failing plugin

vagrant plugin repair vagrant-vboxmanage
Note: The vagrant plugin repair command attempts to resolve common plugin issues by reinstalling or updating dependencies. If this fails, manual uninstall and reinstallation may be required.

9. Expunging Plugins

To remove a Vagrant plugin that is no longer needed, use the vagrant plugin uninstall command followed by the plugin name.

Command Description Notes
vagrant plugin uninstall <plugin-name> Uninstalls a specific plugin Replace <plugin-name> with the actual plugin name

Example: Uninstalling a Plugin

vagrant plugin uninstall vagrant-vsphere

Running this command will remove the plugin from your Vagrant environment and clean up any associated files or configurations.

Note: Ensure that no Vagrant boxes or environments are currently using the plugin before uninstalling it to avoid breaking dependencies.

10. Developing Custom Plugins

Example: Basic Plugin Structure

require "vagrant"

module VagrantPlugins
  module ExamplePlugin
    class Plugin < Vagrant::Plugin::V2::Plugin
      name "example"
      version "0.1.0"

      config :example do
        Config.new
      end

      command :example do
        Command.new
      end
    end
  end
end
Component Description Notes
name "example" Unique identifier for the plugin
version "0.1.0" Plugin version string
config Config.new Configuration class for plugin settings
command Command.new CLI command implementation
Note: Plugin classes must inherit from Vagrant::Plugin::V2::Plugin to be recognized by Vagrant.

Example: Plugin Configuration Class

module VagrantPlugins
  module ExamplePlugin
    class Config < Vagrant::Config::V2::Base
      attr_accessor :setting1
      attr_accessor :setting2

      def initialize
        @setting1 = "default"
        @setting2 = false
      end

      def validate(machine)
        errors = []
        errors << "setting1 must not be empty" if @setting1.nil? || @setting1.empty?
        errors
      end
    end
  end
end

Example: Plugin Command Class

module VagrantPlugins
  module ExamplePlugin
    class Command < Vagrant::Command::Base
      def execute(argv, options)
        puts "Hello from Example Plugin!"
      end
    end
  end
end

Plugin Development Workflow

  • Create a Ruby gem structure for the plugin
  • Implement Plugin, Config, and Command classes
  • Register the plugin in Vagrant's plugin registry
  • Test plugin functionality in a Vagrant environment
  • Package and publish the gem to RubyGems.org
Warning: Plugin development requires familiarity with Ruby and Vagrant's internal APIs. Changes to core Vagrant behavior may break compatibility.

Was this article helpful?

Related Cheat Sheets