Advanced install of New Relic Python agent

This document is a detailed guide showing how to install New Relic for Python. For simpler install instructions that will work for the majority of Python frameworks (including Django), see the Standard install guide. Read this advanced guide only if you cannot use the standard install, or if you'd like more understanding of the install steps.


Before you install New Relic for Python:

Overview of install process

Here's an overview of how to install the New Relic Python agent:

  1. Download and install the New Relic package
  2. Create config file
  3. Integrate the New Relic agent with your app
  4. Restart your app

These steps are described in more detail in the following sections.

If you use the hosting service Heroku, see Heroku install for more information.

If you want to instrument non-web scripts, worker processes, tasks, and functions, see Monitor scripts and functions.

1. Download and install

Download and install the New Relic Python agent package using your preferred procedure. Some common install procedures are:

pip install (RECOMMENDED)

Install the newrelic package directly from PyPi by running:

pip install newrelic


easy_install newrelic

pip install is recommended, because pip will correctly remove old versions of the agent when upgrading.

Buildout install

Install the package by creating an appropriate section for the newrelic package using the zc.recipe.egg recipe.

Manual download and install

To obtain the package manually:

  1. Download the appropriate tar.gz file from the download site.
  2. Unpack the tar.gz file.
  3. In the top directory of the unpacked package, install it by running:

    python install

This should be the python executable for the Python installation or virtual environment where you want to install the Python agent software. If installing into a system-wide Python installation, use the sudo command or run the command as root.

2. Create config file

Next, you will create a configuration file for the New Relic Python agent. The config file is the main way to customize the New Relic agent's behavior. (The other methods are using the UI or using environment variables.)

To create the agent config file:

After you've installed the New Relic Python package, the newrelic-admin script will be in the same directory as the Python executable. In that directory, run:

newrelic-admin generate-config YOUR_LICENSE_KEY newrelic.ini

The generate-config command creates the config file. newrelic.ini is the recommended name for the config file. For instructions on how to find your New Relic license key, see New Relic license key.

3. Integrate the agent

The next step is integrating the Python agent with your application so that your app's major functions and web requests are captured by the agent. This is done by running the newrelic-admin script in front of your usual app startup command.

If you use one of the following services, select it to read some caveats before continuing to the admin script instructions.


The New Relic Python agent can be used with uWSGI version 1.2.6 or higher. The recommended integration method (using the admin script via the command line) can be used for uWSGI, but you will need to supply certain specific command line options to the uwsgi executable. The additional options you must use are:

Option Purpose
--enable-threads By default uWSGI does not enable threading support within the Python interpreter core. This means it is not possible to create background threads from Python code. As the Python agent relies on being able to create background threads, this option is required. This option will be automatically applied if uWSGI is configured for multiple threads using the --threads option.
--single-interpreter By default uWSGI will execute Python code within a sub interpreter of the process rather than the main Python interpreter created when Python is first initialized. This is done to allow multiple separate Python web applications to be run within the one process but to be sufficiently separated so as to not interfere with each other. Older versions of uWSGI can fail however when using sub interpreters with threading enabled. It is therefore safest to use this option and restrict yourself to a single web application per process. Running a single web application in each process with uWSGI is the normal use case so it would be unlikely that this restriction would be an issue.

If you use mod_wsgi, the recommended integration method (running the admin script via the command line) is not possible and you must manually integrate the Python agent in your app code.

If you use mod_wsgi-express, you can use the recommended integration method and you can continue reading the instructions in this document. For more information, see the New Relic mod_wsgi documentation.

Tornado 4

New Relic provides introductory support for Tornado 4. Use of Tornado 4 requires activation with a feature flag. For more on this, see New Relic for Tornado 4.


Python web applications on WebFaction typically use Apache/mod_wsgi. With mod_wsgi, it is not possible to use the recommended admin script method; you must use a manual integration method.

If you're using mod_wsgi-express, you can use the admin script via the command line and you can continue reading the instructions in this document.

To run the newrelic-admin script via the command line, place the following in front of your standard app startup command:

  1. The path to the New Relic config file
  2. The newrelic-admin run-program script command

For example, if you use Gunicorn (a Python web server) and your startup command is:

gunicorn -w 3 wsgi:application

Then the new command would be:

NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program gunicorn -w 3 wsgi:application

The above instructions are for a Bourne-style shell. You may need to adjust these instructions for a different shell.

For more details about using the admin script, see Running the admin script from command line. If you cannot use the admin script method or don't want to, see the manual integration method.

4. Restart app and check for data

When you've finished the integration procedure:

  1. Restart your app server.
  2. Wait five minutes.
  3. Check for data showing up in your New Relic charts.

If data is not showing up, see Troubleshooting: No data appears.

What's next?

If you've gotten New Relic working for your Python app, here are some suggested next steps:

For more help

Join the discussion about Python in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at