Ruby agent installation

Video For Ruby agent installation tips, watch this New Relic video (less than 1 minute).

Installing the gem

New Relic recommends installing the Ruby gem in order to have better control over versions and dependencies. However, the gem is not supported for Rails versions prior to 2.0. If you are using Rails 1.2.6 and earlier, install the plugin.

Our gem is available on as newrelic_rpm:

 sudo gem install newrelic_rpm

For Rails 3 and installations using Bundler, simply add our gem to the Gemfile:

gem 'newrelic_rpm'

For Rails versions 2.1 to 2.3 without Bundler, edit environment.rb and add to the initializer block:

config.gem "newrelic_rpm"

For Rails versions 2.0.*, edit environment.rb and add this statement after the initializer block:

require "newrelic_rpm"

Installing the configuration file

After installing the agent, copy the newrelic.yml file into the config subdirectory of your application. You can download a fresh newrelic.yml that includes your license key from the Account Settings link when logged in to

Note: As part of the installation process, change the default application name to a meaningful name.

Updating the newrelic.yml file

Whenever you update the agent, double-check that your Agent configuration file (config/newrelic.yml) is up to date. To do this, you'll need to do a visual inspection of the default newrelic.yml file that lives in the Agent plugin folder (vendor/plugins/newrelic_rpm/newrelic.yml). Look for new configuration options that aren't in your config/newrelic.yml file.

Updating the agent

sudo gem update newrelic_rpm

Installing outside production environments

Typically you will install New Relic in your production environment to get the most out of our performance reporting features for your applications. If you want to try out the Ruby agent in a development or localhost environment, be aware that by default, New Relic will not report any metrics.

To deploy New Relic outside your production environment and still be able to view your app's performance metrics: In your newrelic.yml file's development: block, change the monitor_mode config value to true.

For more information about using New Relic's Ruby agent outside production environments, see Developer mode.

Installing with the Bundler gem

In versions 2.13 and above, the New Relic Ruby agent will properly handle Bundler initialization under Rails 3 and Rails 2.3.

Add the gem specification to your Gemfile. Recommendation: Place the New Relic gem as low in the list as possible, allowing the frameworks above it to be instrumented when the gem initializes:

gem 'newrelic_rpm'

Note: This approach only works for Bundler versions starting with 1.0.0. For more information on the bundler gem, see the bundler github project.

Uninstalling the Ruby agent gem

If you installed the plugin as a gem, remove all references to newrelic_rpm from your environment.rb file.

For more help

Additional documentation resources include:

  • Ruby agent configuration (general configuration settings, proxy, transaction tracer, error collection, and updates)
  • New Relic for Ruby (overview of compatibility and requirements, installation, configuration, troubleshooting, known issues, advanced features, and beta releases)

If you need additional help, get support at