Install the New Relic Python agent

New Relic for Python monitors your Python application, helping you get insight into performance issues. This document explains how to get New Relic for Python installed and reporting data.

This document gives you helpful context and details about install steps. For very simple install instructions that will work for most WSGI web frameworks (including Django), see the Quick start guide.


Before you install New Relic for Python, you must have a New Relic account. If you don't yet have an account, go to the New Relic sign-up page to create one.

You will also need your New Relic license key number.

If you use one of these hosting services, select it for instructions:

Overview of install process

New Relic for Python supports a number of web frameworks and libraries right out of the box. If you use one of the many supported web frameworks, installation is easy. If you use an unsupported framework, the process will involve some additions to your app code and/or web server files.

Here's an overview of the major install steps:

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

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

Download and install

Download and install the New Relic Python agent package using your preferred procedure. Some common install procedures are below. pip is the recommended install method.

pip install

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.

Create configuration file

The New Relic agent's config file is the main way to customize the New Relic agent's behavior. (The other methods are via the UI or via environment variables.)

To create the agent config file:

  • After the New Relic Python package installation, a newrelic-admin script will be in the same directory as the Python executable. In that directory, run the following:

    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 more on how to find your New Relic license key, see New Relic license key.

For in-depth details on how to use the admin script, see Python agent admin script.

Integrate New Relic with your app

Next, you must integrate the Python agent with your application so that important functions and web requests are captured by the agent and sent to New Relic.

There are two integration methods:

  • Run the newrelic-admin script via the command line (recommended)
  • Initialize the Python agent in your web app code

Running the admin script from the command line is recommended because it doesn't require changing your app code. It's possible with most Python set-ups. If you use one of the following web frameworks or servers, select it to read special requirements.


The New Relic Python agent can be used with uWSGI version 1.2.6 or higher. The recommended command line admin script method 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:

Continue reading the install instructions for more on using the command line admin script.

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, running the admin script via the command line is not possible and you must use manual integration in your app code. If you use mod_wsgi-express, you can use the admin script via the command line and you can continue reading the procedures on this page. 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 info, see New Relic Tornado 4 documentation.

Run admin script via command line

To run the newrelic-admin script via the command line:

  • Via your startup shell script or the command line, place the newrelic-admin run-program script command in front of your usual startup commands.

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

gunicorn -w 3 wsgi:application

Then your new New Relic-integrated command would be:

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 information on this method, see Running the admin script from the command line.

Manual integration in application code

The second option for integration is to manually initialize the Python agent in your application code. (You might use this, for example, if you have an embedded Python environment). This is not the recommended method; it is recommended to use the admin script method.

To learn more about this option, see Manual integration in app code.

Restart app and check for data

When you're finished the integration procedure:

  1. Restart your app server.
  2. Wait five minutes.
  3. Check for data showing up in the New Relic APM 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