Plugins

RuboCop can be extended with additional cops and formatters. There are many official plugins maintained by RuboCop’s team, as well as third-party ones.

Loading Plugins

Since RuboCop 1.72, the recommended way to load extensions is through the plugin system, which is based on lint_roller. Older extensions that haven’t been updated yet can still be loaded via require.

Refer to the Plugin Migration Guide when migrating existing configurations from require to plugins.

Loading Plugin Extensions

The plugin system was introduced in RuboCop 1.72.

Besides the --plugin command line option you can also specify ruby files that should be loaded with the optional plugins directive in the .rubocop.yml file:

plugins:
  - rubocop-performance

Most extension gems with plugin support should work with the example above.

The following is an example of a plugin that is not published as a gem:

plugins:
  - rubocop-extension:
      require_path: path/to/extension/plugin
      plugin_class_name: RuboCop::Extension::Plugin

There are other ways to specify this. For more details, please refer to the lint_roller documentation.

Loading Legacy Extensions via require

Besides the --require command line option you can also specify ruby files that should be loaded with the optional require directive in the .rubocop.yml file:

require:
  - ../my/custom/file.rb
  - rubocop-extension

The extension loading via require remains compatible with the pre-plugin inject method. Since require is used for internal extensions such as custom cops and formatters, there are no plans to remove it in the future. However, it is recommended that publicly available extension cops in gems migrate to the plugin system.

The paths are directly passed to Kernel.require. If your extension file is not in $LOAD_PATH, you need to specify the path as relative path prefixed with ./ explicitly or absolute path. Paths starting with a . are resolved relative to .rubocop.yml. If a path containing - is given, it will be used as is, but if we cannot find the file to load, we will replace - with / and try it again as when Bundler loads gems.

Plugin Suggestions

Depending on what gems you have in your bundle, RuboCop might suggest plugins that can be added to provide further functionality. For instance, if you are using rspec without the corresponding rubocop-rspec plugin, RuboCop will suggest enabling it.

This message can be disabled by adding the following to your configuration:

AllCops:
  SuggestExtensions: false

Suggest default extensions if SuggestExtensions: true.

You can also opt-out of suggestions for a particular plugin as so (unspecified plugins will continue to be notified, as appropriate):

AllCops:
  SuggestExtensions:
    rubocop-rake: false

Custom Cops

You can configure the custom cops in your .rubocop.yml just like any other cop.

If you’d like to create a plugin gem, you can use rubocop-extension-generator.

For plugin specifications, please refer to lint_roller.

See Development to learn how to implement a cop.

Available Plugins

The main RuboCop gem focuses on the core Ruby language and doesn’t include functionality related to any external Ruby libraries/frameworks. There are, however, many RuboCop plugins dedicated to those and a few of them are maintained by RuboCop’s Core Team.

Official Plugins

Third-party Plugins

Any plugins missing? Send us a Pull Request!