<commit_before>---
layout: "docs"
page_title: "Plugin Development Basics - Plugins"
sidebar_current: "plugins-development-basics"
description: |-
  Plugins are a great way to augment or change the behavior and functionality
  of Vagrant. Since plugins introduce additional external dependencies for
  users, they should be used as a last resort when attempting to
  do something with Vagrant.
---

# Plugin Development Basics

Plugins are a great way to augment or change the behavior and functionality
of Vagrant. Since plugins introduce additional external dependencies for
users, they should be used as a last resort when attempting to
do something with Vagrant.

But if you need to introduce custom behaviors
into Vagrant, plugins are the best way, since they are safe against future
upgrades and use a stable API.

<div class="alert alert-warning">
  <strong>Warning: Advanced Topic!</strong> Developing plugins is an
  advanced topic that only experienced Vagrant users who are reasonably
  comfortable with Ruby should approach.
</div>

Plugins are written using [Ruby](https://www.ruby-lang.org/en/) and are packaged
using [RubyGems](https://rubygems.org/). Familiarity with Ruby is required,
but the [packaging and distribution](/docs/plugins/packaging.html) section should help
guide you to packaging your plugin into a RubyGem.

## Setup and Workflow

Because plugins are packaged as RubyGems, Vagrant plugins should be
developed as if you were developing a regular RubyGem. The easiest
way to do this is to use the `bundle gem` command.

Once the directory structure for a RubyGem is setup, you will want
to modify your Gemfile. Here is the basic structure of a Gemfile for
Vagrant plugin development:

```ruby
source "https://rubygems.org"

group :development do
  gem "vagrant", git: "https://github.com/mitchellh/vagrant.git"
end

group :plugins do
  gem "my-vagrant-plugin", path: "."
end
```

This Gemfile gets "vagrant" for development. This allows you to
`bundle exec vagrant` to run Vagrant with your plugin already loaded,
so that you can test it manually that way.

The only thing about this Gemfile that may stand out as odd is the
"plugins" group and putting your plugin in that group. Because
`vagrant plugin` commands do not work in development, this is how
you "install" your plugin into Vagrant. Vagrant will automatically
load any gems listed in the "plugins" group. Note that this also
allows you to add multiple plugins to Vagrant for development, if
your plugin works with another plugin.

With this structure in place, your workflow should be like any other
Ruby project, with one exception.  Because Vagrant uses the internal
APIs of Bundler, the version of Bundler used for Vagrant development
is pinned to a specific range defined in the
[vagrant.gemspec](https://github.com/mitchellh/vagrant/blob/master/vagrant.gemspec)
file.  If the upper bound version is `1.10.6`, then install the 
required version of Bundler and Vagrant dependencies with the
following commands:

```
gem install bundler --version '1.10.6' && \
bundle _1.10.6_ install
```

*Be sure to check [vagrant.gemspec](https://github.com/mitchellh/vagrant/blob/master/vagrant.gemspec)
and use the upper bound version of Bundler*

When you want to manually test your plugin, use
`bundle exec vagrant` in order to run Vagrant with your plugin
loaded (as we specified in the Gemfile).
<commit_msg>Replaces Bundler details with Wiki link<commit_after>---
layout: "docs"
page_title: "Plugin Development Basics - Plugins"
sidebar_current: "plugins-development-basics"
description: |-
  Plugins are a great way to augment or change the behavior and functionality
  of Vagrant. Since plugins introduce additional external dependencies for
  users, they should be used as a last resort when attempting to
  do something with Vagrant.
---

# Plugin Development Basics

Plugins are a great way to augment or change the behavior and functionality
of Vagrant. Since plugins introduce additional external dependencies for
users, they should be used as a last resort when attempting to
do something with Vagrant.

But if you need to introduce custom behaviors
into Vagrant, plugins are the best way, since they are safe against future
upgrades and use a stable API.

<div class="alert alert-warning">
  <strong>Warning: Advanced Topic!</strong> Developing plugins is an
  advanced topic that only experienced Vagrant users who are reasonably
  comfortable with Ruby should approach.
</div>

Plugins are written using [Ruby](https://www.ruby-lang.org/en/) and are packaged
using [RubyGems](https://rubygems.org/). Familiarity with Ruby is required,
but the [packaging and distribution](/docs/plugins/packaging.html) section should help
guide you to packaging your plugin into a RubyGem.

## Setup and Workflow

Because plugins are packaged as RubyGems, Vagrant plugins should be
developed as if you were developing a regular RubyGem. The easiest
way to do this is to use the `bundle gem` command.

Once the directory structure for a RubyGem is setup, you will want
to modify your Gemfile. Here is the basic structure of a Gemfile for
Vagrant plugin development:

```ruby
source "https://rubygems.org"

group :development do
  gem "vagrant", git: "https://github.com/mitchellh/vagrant.git"
end

group :plugins do
  gem "my-vagrant-plugin", path: "."
end
```

This Gemfile gets "vagrant" for development. This allows you to
`bundle exec vagrant` to run Vagrant with your plugin already loaded,
so that you can test it manually that way.

The only thing about this Gemfile that may stand out as odd is the
"plugins" group and putting your plugin in that group. Because
`vagrant plugin` commands do not work in development, this is how
you "install" your plugin into Vagrant. Vagrant will automatically
load any gems listed in the "plugins" group. Note that this also
allows you to add multiple plugins to Vagrant for development, if
your plugin works with another plugin.

With this structure in place, your workflow should be like any other
Ruby project, with one exception.  Because Vagrant uses the internal
APIs of Bundler, see [Installing Vagrant from Source](https://github.com/mitchellh/vagrant/wiki/Installing-Vagrant-from-Source)
for tips for using the correct version of Bundler to install
dependencies.

When you want to manually test your plugin, use
`bundle exec vagrant` in order to run Vagrant with your plugin
loaded (as we specified in the Gemfile).

{'fraction_non_alphanumeric': 0.060794044665012405, 'fraction_numerical': 0.0018610421836228288, 'mean_word_length': 4.583549783549784, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 11, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1787276', 'n_tokens_mistral': 1764, 'n_tokens_neox': 1713, 'n_words': 905}