---
title: Install the New Relic Ruby agent
source: https://docs.newrelic.com/docs/apm/agents/ruby-agent/installation/install-new-relic-ruby-agent
---

Our Ruby agent auto-instruments your code so you can start monitoring applications. You can use our launcher, or follow the instructions in this document to complete a basic Ruby agent installation.

[Add Ruby data](https://one.newrelic.com/launcher/nr1-core.settings?pane=eyJuZXJkbGV0SWQiOiJ0dWNzb24ucGxnLWluc3RydW1lbnQtZXZlcnl0aGluZyJ9&cards[0]=eyJuZXJkbGV0SWQiOiJzZXR1cC1uZXJkbGV0cy5zZXR1cC1ydWJ5LWludGVncmF0aW9uIiwiYWNjb3VudElkIjoyNjQwNDA5fQ==&platform[accountId]=1)

> #### 💡 TIP
>
> Is your application running on a Kubernetes cluster? Try out our installation method using the [Kubernetes APM auto-attach](https://docs.newrelic.com/docs/kubernetes-pixie/kubernetes-integration/installation/k8s-agent-operator/).

## Install the gem [#Installing_the_Gem]

> #### ⚠️ IMPORTANT
>
> If you are using the agent in a Docker container, install the agent **within each** container.

1.  The Ruby agent's gem is available from [rubygems.org](https://rubygems.org/) as `newrelic_rpm`. For applications using Bundler, add this gem to the Gemfile:

    ```ruby
    gem 'newrelic_rpm'
    ```
2.  To use Infinite Tracing, the Infinite Tracing gem is also available from rubygems.org as `newrelic-infinite_tracing`. For applications using Bundler, additionally include the Infinite Tracing gem in the Gemfile:

    ```ruby
    gem 'newrelic-infinite_tracing'
    ```
3.  The next step varies depending on if you are using Rails, Roda, or Sinatra:

    | **Ruby installation**               | **Comments**                                                                                                                                                                                                                                                                                                                                                                                                                                               |
    | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | If using Rails, Roda, or Sinatra    | - **Rails**: Rails will automatically call `Bundler.require` and cause `newrelic_rpm` to be required during startup of your application. - **Roda, Sinatra**: If you're using Roda, Sinatra or another framework, you must manually call `require 'newrelic_rpm'`. Additionally, if you're using Infinite Tracing, manually call `require 'newrelic/infinite_tracing'`. Alternately, manually call `Bundler.require`, which also enables Infinite Tracing. |
    | If not using Rails, Roda or Sinatra | In order to use automatic browser application monitoring in a Rack application that does **not** use Roda, Sinatra, or Rails, you must manually include additional [Rack middlewares](https://docs.newrelic.com/docs/agents/ruby-agent/frameworks/rack-middlewares#manual) provided by the agent. Place the New Relic gem as low in the list as possible, allowing the frameworks above it to be instrumented when the gem initializes.                    |

## Install the configuration file [#Configuration_file]

After installing the agent, you will need to install the `newrelic.yml` configuration file, and name your app:

1.  Download a copy of [`newrelic.yml`](https://github.com/newrelic/newrelic-ruby-agent/blob/dev/newrelic.yml) from our GitHub repo.
2.  Copy the `newrelic.yml` file into the `config` sub-directory of your application.
3.  Edit the `license_key` value to include your license key.
4.  Edit the `app_name` value to [a meaningful name](https://docs.newrelic.com/docs/agents/manage-apm-agents/app-naming/name-your-application).

Alternatively, you can generate a `newrelic.yml` file manually with the following command:

```sh
newrelic install --license_key="YOUR_LICENSE_KEY" "YOUR_APP_NAME"
```

You may also use the `--force` option with this command if you need to overwrite an existing `newrelic.yml`.

## View logs for your APM and infrastructure data [#logs-context]

You can also bring your logs and application's data together to make troubleshooting easier and faster. With [logs in context](https://docs.newrelic.com/docs/logs/logs-context/configure-logs-context-ruby/), you can see log messages related to your errors and traces directly in your app's UI. You can also see logs in context of your [infrastructure data](https://docs.newrelic.com/docs/logs/forward-logs/forward-your-logs-using-infrastructure-agent/), such as Kubernetes clusters. No need to switch to another UI page.

## Update the agent [#Updating_the_Agent]

See [Upgrade Ruby agent versions](https://docs.newrelic.com/docs/agents/ruby-agent/installation/upgrade-ruby-agent-versions).

## Install agent outside production environments [#Outside_production_environments]

Typically you will install the Ruby agent in your production environment. If you want to try out the Ruby agent in a development or localhost environment, verify in the relevant `environment:` block of the `newrelic.yml` file that the `monitor_mode` config value has been set to `true`.

For example, to deploy New Relic in your [development environment](https://docs.newrelic.com/docs/ruby/developer-mode) and still be able to view your app's performance metrics: In the `development:` block, set the `monitor_mode` config value to `true`.

## Uninstall the Ruby agent gem [#Uninstalling_Gem]

To uninstall the Ruby agent using Bundler, remove `gem 'newrelic_rpm'` from your Gemfile. If you are not using Bundler, remove all references to `newrelic_rpm` from your `environment.rb` file.