• Log in

Install the Python agent for Docker

You can use the Python agent to instrument Python applications deployed in Docker containers. This document will show you how to build, configure, and deploy an instrumented version of your Dockerized Python application.

Build your instrumented container

This Dockerfile provides a base for your Python Docker image by installing the Python agent. You can customize it by changing the FROM instruction, for example to use another version of Python or a different Linux distribution.

  1. To get started, copy the code block below and save it as a new Dockerfile in your directory.

    FROM python:3.6-alpine
    RUN pip install --no-cache-dir newrelic
    ENTRYPOINT ["newrelic-admin", "run-program"]
  2. Build the base image:

    $ docker build -t python_newrelic:latest .
  3. You can use the new image as the base for your own Dockerfile, replacing your FROM line with FROM python_newrelic:latest. You'll need to put your app's command line in a CMD instruction, not in ENTRYPOINT, so that the newrelic-admin program can start it. For example:

    CMD ["gunicorn", "-b :5000", "myapp:app"]
  4. To enable the agent, you'll need to configure it with environment variables. The NEW_RELIC_LICENSE_KEY and NEW_RELIC_APP_NAME variables are required. If you use docker run, for example, you can add -e options:



    If you're using docker-compose, you can use secrets to manage your license key.

Configure the agent

When configuring the agent, you have two options:

Recommended: Set the configuration with environment variables

You can configure most agent settings with environment variables. You can do this at run time with the -e parameter to docker run, for example:

$ docker run -e NEW_RELIC_APP_NAME="A Different App" \
        -e NEW_RELIC_LOG=stdout \

Or you can include environment variables in your Dockerfile:

NEW_RELIC_APP_NAME="My Application"
# etc.


We strongly recommend not putting your license key in your Dockerfile or Docker image. Instead, set it at run time with the -e option.

Use a configuration file

When you can't or don't want to set options with environment variables, you can do this with a configuration file.

If you want to configure the Python agent with a configuration file, you can either add your newrelic.ini file to your Docker image at build time or mount the file at run time. The file needs to be placed in your app's root directory.


If you choose to use file-based configuration, you must remove the license_key setting in the file, and any other settings you want to set with environment variables. Otherwise, the default value in the file will override the environment variable. We strongly recommend not including your license key in the Docker image.

  1. Generate or download the newrelic.ini file described in the Python agent configuration docs.

  2. Edit the newrelic.ini file to configure your settings. See the Python agent configuration documentation for more details.

  3. Chose one of the following options:

    • Option 1: ADD the newrelic.ini file to your Docker image at build time. Add this line to your Dockerfile, replacing the placeholder with the path to your app (either relative to your WORKDIR or absolute) and build it you normally would.

      ADD newrelic.ini /PATH/TO/YOUR/APP
    • Option 2: Mount the newrelic.ini file at run time. Add the -v switch below to your docker run command, replacing /PATH/TO/YOUR/APP with the absolute path to your app's base directory in the Docker image.

      $ docker run -v /local/path/to/newrelic.ini:/PATH/TO/YOUR/APP/newrelic.ini \
Copyright © 2022 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.