Server Mode

The server mode was introduced in RuboCop 1.31. If you’re using an older RuboCop version you can check out the rubocop-daemon project that served as the inspiration for RuboCop’s built-in functionality.

You can reduce the RuboCop boot time significantly (something like 850x faster) by using the --server command-line option.

The --server option speeds up the launch of the rubocop command by utilizing a standalone server process that loads the RuboCop runtime production files (i.e. require 'rubocop').

Normally RuboCop starts somewhat slowly because it needs to require a ton of files and that’s fairly slow. With the RuboCop server we sidestep this nasty issue and make it much more pleasant to interact with RuboCop from text editors and IDEs.

The feature cannot be used on JRuby and Windows, as they do not support the fork system call.

Run with Server

There are two ways to enable server:

  • rubocop --server: If server process has not started yet, start server process and execute inspection with server.

  • rubocop --start-server: Just start server process.

When the server is started, it outputs the host and port.

$ rubocop --start-server
RuboCop server starting on 127.0.0.1:55772.
The rubocop command is executed using the server process if a server is started. Whenever a server process is not running, it will load the RuboCop runtime files and execute. (same behavior as with RuboCop 1.30 and lower)

If a server is already running, the command only displays the server’s PID. A new server will not be started.

$ rubocop --start-server
RuboCop server (16060) is already running.

The server process name is basically rubocop --server and the project directory path:

$ ps aux | grep 'rubocop --server'
user             16060   0.0  0.0  5078568   2264   ??  S     7:54AM   0:00.00 rubocop --server /Users/user/src/github.com/rubocop/rubocop
user             16337   0.0  0.0  5331560   2396   ??  S    23:51PM   0:00.00 rubocop --server /Users/user/src/github.com/rubocop/rubocop-rails

When you run bundle update or update a local config file (e.g., .rubocop.yml or .rubocop_todo.yml), and then run rubocop, the server process will automatically restart.

$ rubocop --server
RuboCop version incompatibility found, RuboCop server restarting...
RuboCop server starting on 127.0.0.1:60665.

If you would like to start the server in the foreground, which can be useful when running within Docker, you can pass the --no-detach option.

$ rubocop --start-server --no-detach

Restart Server

The started server does not reload the configuration file. You will need to restart the server when you upgrade RuboCop or change the RuboCop configuration.

$ rubocop --restart-server
RuboCop server starting on 127.0.0.1:55822.

Command Line Options

These are the command-line options for server operations:

Command flag Description

--server

If a server process has not been started yet, start the server process and execute inspection with server.

--no-server

If a server process has been started, stop the server process and execute inspection without the server.

--restart-server

Restart server process.

--start-server

Start server process.

--stop-server

Stop server process.

--server-status

Show server status.

--no-detach

Run the server process in the foreground.
You can specify the server host and port with the $RUBOCOP_SERVER_HOST and the $RUBOCOP_SERVER_PORT environment variables.

If RUBOCOP_OPTS environment variable or .rubocop file contains --server option, rubocop command defaults to server mode. Other server options such as stop-server, restart-server specified on the command line will take precedence over them.

Environment Variables

You can change the startup host and port of server process with environment variables.

  • $RUBOCOP_SERVER_HOST

  • $RUBOCOP_SERVER_PORT

The following is an example:

$ RUBOCOP_SERVER_PORT=98989 rubocop --start-server