Getting Started

This guide will get you up and running with RuboCop in a few minutes. RuboCop serves three primary roles:

  1. Code style checker (a.k.a. linter) — enforces style conventions from the Ruby Style Guide

  2. Lint tool — catches bugs and suspicious code, like a smarter ruby -w

  3. Code formatter — automatically fixes layout and formatting

First Run

After installing RuboCop, just run it from your project’s root directory:

$ rubocop

RuboCop will recursively check all Ruby files and report any offenses it finds:

Inspecting 5 files
.W.C.

Offenses:

lib/foo.rb:2:3: C: Style/IfUnlessModifier: Favor modifier if usage when having a single-line body.
  if something
  ^^
lib/bar.rb:5:5: W: Lint/UselessAssignment: Useless assignment to variable - x.
    x = 42
    ^

5 files inspected, 2 offenses detected

Each offense shows the file, line, column, severity (C for convention, W for warning, E for error), the cop name, and a description. The letter on the progress line (. = clean, C/W/E = offense found) gives you a quick overview.

Setting Up Your Project

For an existing project with many offenses, the easiest way to get started is to generate a TODO file:

$ rubocop --auto-gen-config

This creates two files:

  • .rubocop_todo.yml — temporarily disables all current offenses

  • .rubocop.yml — your configuration file (with inherit_from: .rubocop_todo.yml added)

Now rubocop will pass cleanly, and you can work through the TODO entries at your own pace. See Auto-generating Configuration for details.

For a new project, you can generate a starter config file instead:

$ rubocop --init

Customizing RuboCop

All configuration lives in .rubocop.yml. Here are a few common adjustments:

# Increase the maximum line length
Layout/LineLength:
  Max: 120

# Disable a cop entirely
Style/Documentation:
  Enabled: false

# Restrict a cop to specific files
Rails/HasAndBelongsToMany:
  Include:
    - app/models/**/*.rb

See Configuration for the full reference.

Fixing Offenses Automatically

Many cops can autocorrect the problems they find. Use -a for safe corrections only, or -A to include unsafe ones:

# Safe autocorrections only
$ rubocop -a

# All autocorrections (safe and unsafe)
$ rubocop -A

# Fix only formatting (layout) offenses
$ rubocop -x
Review the diff after running autocorrect, especially with -A. See Autocorrect for more details on safe vs. unsafe corrections.

Editor Integration

For the best experience, set up RuboCop in your editor so you get real-time feedback as you type. RuboCop has a built-in LSP server that works with any editor that supports the Language Server Protocol.

The recommended setup for popular editors:

  • VS Code — Install the Ruby LSP extension

  • Emacs — Use Eglot (built-in since Emacs 29) or lsp-mode

  • Vim/Neovim — Use the built-in LSP client or ALE

See Integration with Other Tools for more editors and alternative approaches.

Next Steps