---
layout: docs
page_title: Plugins
description: |-
  Waypoint can be extended using custom plugins. Waypoint supports custom builders, deployment platforms, registries, release managers, and more.
---

# Plugins

Waypoint can be extended using custom plugins. Waypoint supports
custom builders, deployment platforms, registries, release managers,
and more. This allows you to extend the Waypoint workflow and featureset
anywhere. This page will focus on _using_ plugins. To learn more about
how to write plugins, see the [Extending Waypoint guide](/docs/extending-waypoint).

Waypoint ships with dozens of built-in plugins. These plugins are available
out-of-the-box with Waypoint and are built directly on the same plugin system
as external plugins. To see a list of supported plugins, see the
[plugin documentation](/plugins).

## Available Plugins

You can see a list of [all built-in plugins here](/plugins).

We do not maintain a list of external plugins currently.

## Using an External Plugin

External plugins are distributed as executable binaries. To use an external
plugin, you must download the correct binary for your operating system,
place it at the correct location, and use it within your
[waypoint configuration](/docs/waypoint-hcl/use).

### Installing an External Plugin - Local Operations

To install an external plugin, the binary must first be named
`waypoint-plugin-<name>` where `<name>` is the same label that is used
with the [`use` stanza](/docs/waypoint-hcl/use) in your Waypoint configuration.
For the example below, our binary must be named `waypoint-plugin-hashicloud`.
If you're on Windows, the binary must end in ".exe".

```hcl
app {
  # ...

  deploy {
    use "hashicloud" {}
  }
}
```

Once the plugin is named, it must be copied into the correct location. Waypoint
will look for plugins in the following locations in the following order:

1. In the same directory as the `waypoint.hcl` file.
2. In `./.waypoint/plugins/` relative to the `waypoint.hcl` file.
3. In `$XDG_CONFIG_HOME/waypoint/plugins`

Once a plugin is found, it will not search the later paths.

### Installing an External Plugin - Remote Operations

In order to use a custom plugin with remote operations, the plugin must be built-in
to the Docker image used for the on-demand runner profile configured to execute your
remote operations. The default on-demand runner image, hashicorp/waypoint-odr:latest,
contains only the plugins which are built-in to the Waypoint binary. To add a custom
plugin, you may extend this image to add your own plugin:

```Dockerfile
FROM hashicorp/waypoint:latest

COPY ./waypoint-plugin-myplugin $HOME/.config/waypoint/plugins/waypoint-plugin-myplugin
```

How to configure your runner profile to use the new image is detailed [here](/docs/runner/profiles#oci-url).

#### Troubleshooting

If you're seeing `waypoint init` errors that a plugin cannot be found,
run `waypoint init` with the `-vv` flag and look for the line that says
"plugin search path". This will list the search path that Waypoint is
using for finding your plugins.

If the path isn't correct, this is usually due to unset environment variables
(typically `XDG_CONFIG_HOME`). Please verify these are set properly and
try again.

```
2020-10-17T11:32:12.743-0700 [DEBUG] waypoint.runner: plugin search path: job_id=01EMVXARPMVCPYWE4FPECZY30B path=[, .waypoint/plugins, /Users/mitchellh/.config/waypoint/plugins]
```

### Using the External Plugin

The external plugin is used in the same manner as a built-in plugin.
Continuing our example above, you can use an external plugin with a
`use` stanza. The existence of a `use` stanza with a plugin name will
notify Waypoint that it requires that plugin.

```hcl
app {
  # ...

  deploy {
    use "hashicloud" {}
  }
}
```

#### Checksumming

You can also use the explicit [`plugin` stanza](/docs/waypoint-hcl/plugin)
to define plugins.

This stanza provides additional functionality when loading plugins.
The most important is that you can specify a SHA-256 checksum for the
plugin binary which helps prevent tampering with the plugin binary.

### Verify

To verify the plugin works, run `waypoint init` against your project.
This will find the plugin, load it, and also validate any configuration.

## Authoring a Plugin

To write a plugin, see the [Extending Waypoint guide](/docs/extending-waypoint).
