Deregister a plugin

When you remove a plugin from the Vault catalog, the catalog entry removal replicates across the cluster through Vault's storage layer, the same way registration does. Vault does not remove the plugin binary or .zip artifact in plugin_directory — you must clean that up manually on every node.

Warning

Removing a plugin with active mounts causes a delayed, silent failure. Vault does not check the mount table before removing a catalog entry.

The remove command reports success and the live plugin process continues to serve requests. On the next unseal, restart, or explicit sys/plugins/reload/backend, Vault tries to re-instantiate the plugin process, finds no catalog entry, and logs skipping plugin-based mount entry.

The mount remains visible in vault secrets list / vault auth list but the plugin process no longer starts. Every request to that mount will fail until you re-register the plugin or remove the mount.

Disable or remove active mounts before removing their plugin from the catalog, or plan to re-register the plugin right after.

To re-register a plugin after removing it, see Register and enable external plugins.

Before you start

You must have admin permissions for Vault. At minimum, your token policy needs the following capability:

# Deregister plugins from the catalog
path "sys/plugins/catalog/*" {
  capabilities = ["delete", "sudo"]
}

Vault does not allow removing built-in plugins. Vault returns an error if you try. To override a built-in plugin, register an external plugin with the same name instead.
Vault does not allow removing pinned plugin versions. Vault returns an error if you try to remove a version that is currently pinned. Unpin the version first, then remove it.

Remove the plugin from the catalog

To remove an unversioned plugin, specify its type and name:

$ vault plugin deregister <type> <name>

For example:

$ vault plugin deregister secret my-custom-plugin
Success! Deregistered plugin (if it was registered): my-custom-plugin

To remove a specific version of a plugin, include the -version flag:

$ vault plugin deregister -version=<version> <type> <name>

For example:

$ vault plugin deregister -version=v1.0.0 secret my-custom-plugin
Success! Deregistered plugin (if it was registered): my-custom-plugin

Note

The command always reports success, even if the plugin was not in the catalog. The message "if it was registered" is intentional — use the verify step below to confirm the entry was actually removed.

Call the DELETE /sys/plugins/catalog/:type/:name endpoint:

$ curl                                       \
    --request DELETE                         \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    ${VAULT_ADDR}/v1/sys/plugins/catalog/<type>/<name>

To target a specific version, append ?version=<version> to the URL.

Verify the plugin removal

Because the CLI always reports success, confirm the entry is gone with vault plugin list or vault plugin info:

$ vault plugin list <type>

If the plugin name no longer appears in the output, Vault removed the catalog entry. To confirm a specific version is gone:

$ vault plugin info -version=<version> <type> <name>

A "plugin not found" error confirms successful deregistration.