rubocop-performance: Performance Cops as a RuboCop Plugin

An extension, not a second linter

RuboCop Performance is an extension of RuboCop focused on code performance checks, and the pitch is performance optimization analysis for your projects. The design choice that makes it cheap to adopt is that it is not a separate tool. The cops live alongside the standard RuboCop cops and load with them, so a team already running rubocop gets the performance checks without a second configuration, a second invocation or a second CI step. The licence is MIT, the gem is named rubocop-performance, and the project sits in the rubocop organisation, with the documentation hosted on the same docs site as RuboCop itself under docs.rubocop.org/rubocop-performance. The repository is a normal Ruby gem layout with a gemspec, a Rakefile, spec/ and relnotes/ directories, and a changelog/ directory for release note fragments.

Installing the gem and declaring it in a Gemfile

Installation is one gem command.

$ gem install rubocop-performance

If you use bundler, the gem goes in the Gemfile instead, with the require set to false.

The Gemfile entry is `gem 'rubocop-performance', require: false`.

The require: false detail is not decorative. The gem is loaded by RuboCop as a plugin, and the configuration file decides when that happens, so having bundler require it eagerly as well would be the wrong mechanism. The same reasoning explains the three separate ways of enabling the extension that the documentation gives, since a project may want the setting committed in the config, or passed in by a script, or wired into a build task.

Enabling it in .rubocop.yml

The configuration file route is the one most projects will use, and it is a single line.

plugins: rubocop-performance

If you load more than one extension, the same key takes an array.

plugins:
  - rubocop-other-extension
  - rubocop-performance

After that you can run rubocop and it will automatically load the RuboCop Performance cops together with the standard cops. There is a version constraint attached to this mechanism, and it is the one detail worth getting right during an upgrade: the plugin system is supported in RuboCop 1.72 and later, and in earlier versions you use require instead of plugins. So a team on an older RuboCop has a different, older mechanism, and the two forms are not interchangeable.

The command line and the Rake task alternatives

The other two routes are for cases where you do not want the setting in the shared config. From the command line you pass the plugin directly.

$ rubocop --plugin rubocop-performance

That is the option to use in a one-off run or in a script that checks a subset of the tree. The third route configures it inside the Rake task that RuboCop provides.

The Rake form requires `rubocop/rake_task` and pushes the plugin name onto the task's plugins array inside a `RuboCop::RakeTask.new` block.

The plugins array on the task is the same concept as the plugins key in the YAML, expressed in Ruby. The practical reason for having all three is that a monorepo may want a checked-in default configuration, a CI job that adds an extra plugin, and a Rake task that carries the whole set without touching the repository's config file.

Treating the performance cops like any other cop

Once loaded, the cops behave like the rest of the RuboCop set, which is the point of the extension model. The documentation says you may treat the Performance cops just like any other cop, and gives the shape of a department and an exclusion list.

Performance/Size:
  Exclude:
    - lib/example.rb

Every cop lives under a namespace, and the Performance namespace groups the performance ones together, so a configuration file that already excludes generated code or vendored directories can exclude the same paths from performance checks with the same syntax. All cops are located under lib/rubocop/cop/performance, and each contains examples and documentation, which is the convention that makes the generated documentation site possible.

The MRI caveat, which is the real limitation

The compatibility section carries one warning that should shape how you adopt this. Performance cops are all MRI focused and are highly dependent on the version of MRI you are using. That is a much narrower claim than a general linter can make, and it is the right one. A performance check in Ruby is usually about how the interpreter behaves, how allocations land, how a method is dispatched, and what the garbage collector does, and those differ between MRI, JRuby and TruffleRuby, and differ between MRI versions. So a cop that is right on MRI 3.4 may be misleading on another version, and the check is meaningless on a non-MRI runtime. RuboCop Performance is compatible with RuboCop core, and the documentation links to the compatibility documentation for the details of how the two versions are matched.

Maintenance, versioning and how the project is built

The release history shows a steady cadence, with v1.26.0 in September 2025, v1.26.1 in October 2025 and v1.27.0 in August 2026, and the last push to the repository on 2026-09-09, so the extension is maintained alongside RuboCop core rather than abandoned. The repository layout reflects the conventions of the RuboCop organisation, with a .rspec file for the test runner configuration, a .rubocop.yml and a .rubocop_todo.yml, a .yamllint.yml for the configuration linting, a .yardopts file for the documentation generator, and a codespell.txt. The tasks/ and bin/ directories hold the task definitions and executables, config/ holds the default configuration for the cops, and relnotes/ holds the release note fragments that become the changelog. The project is a contributor-friendly one, with the contribution guidelines in CONTRIBUTING.md and a Discord channel linked from the readme for questions about the rules themselves.

Editorial conclusion

rubocop-performance fits a Ruby team that already runs RuboCop and wants performance checks reviewed alongside the rest of its cops, without a second tool to install and configure. It is the wrong choice if you need guarantees rather than hints, since the cops are advisory and MRI focused, and the wrong choice for code that does not run on MRI, since the documentation says the performance cops are all MRI focused and highly dependent on the version of MRI you are using. Before enabling the whole set, run it on one directory and read what it reports before you decide what to exclude.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. rubocop/rubocop-performance on GitHub