Python agent installation

For most supported WSGI servers and web frameworks, you can follow the instructions listed in New Relic's Python agent quick start guide. If using Heroku, also see New Relic's Python agent and Heroku.

If the quick start guides do not cover your specific web stack, or if you have special requirements around how the package needs to be installed, then the instructions below may be more appropriate.


[video link] For Python agent installation tips, watch this New Relic video (approximately 1 minute).

Available methods

There are two standard methods to install the newrelic Python package:

  • Download the package manually from our download site and install it using the provided script.
  • Install from the Python Package Index (PyPi) using tools such as pip, easy_install or buildout.

To get the New Relic Python agent working, you need to perform four steps:

  1. Install the newrelic package into your Python installation.
  2. Create and edit the sample Python agent configuration file.
  3. Test the installation.
  4. Modify your application to pull in and initialize the agent.

If you are running your application within a virtual environment, ensure you install the newrelic package within the virtual environment.

Downloading the package

To obtain the package manually:

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

    python install

Note: 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.

Python package index

The New Relic Python agent package is listed on PyPi at

Python package Installation instructions

Install the newrelic package directly from PyPi by running:

pip install newrelic

You can use this method in conjunction with pip requirements files by listing the name of the package (with or without a version qualifier), or the URL to the file on New Relic's download site, and then running:

pip install -r requirements.txt


easy_install newrelic

Recommendation: Use pip instead of easy_install, as pip will correctly remove old versions of the agent software when upgrading.

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

Creating the configuration file

When the newrelic Python package is installed, it will include a newrelic-admin script in the same directory as the Python executable. To create the agent configuration file:

  1. Run the admin script with the command generate-config, and supply your license key. Include a target name for the file to write the configuration file out to.

    newrelic-admin generate-config LICENSE-KEY newrelic.ini
  2. Edit the generated agent configuration file to uncomment the line and set the log file's location where your web application can write to it.

    log_file = /tmp/newrelic-python-agent.log
  3. Change the default application name ("Python Application") to a meaningful name for reporting your application data in the New Relic UI.

Log file options

Depending on your setup, there may be different requirements for your log file. For example:

  • If hosting your web application on a hosting service, verify an absolute path for the log file with the hosting provider.
  • If you are using Apache/mod_wsgi, your application may be running as the Apache user and may have restricted access. You may need to set up a special directory owned by the Apache user where the log file can be placed. Alternatively, you can use log_file = stderr, which should result in the agent log output ending up in your web server error log.

For additional options, see Python agent logging.

Testing the agent configuration

Before you continue, test that the package is installed properly and that details in the configuation file are correct.

From the command line, use the admin script to run:

newrelic-admin validate-config newrelic.ini

If this does not appear to run successfully, see testing the Python agent for potential solutions.

Integrating with your application

After installing and configuring, integrate the Python agent into your app or hosting mechanism:

  1. Refer to the documentation for hosting mechanisms and hosting services.
  2. Follow standard procedures to integrate the Python agent with your application.

For more help

Additional documentation resources include:

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