New Relic Python Agent

11.4.0 verified Tue May 12 auth: no python install: verified quickstart: stale

Official APM agent for Python applications. Auto-instruments web frameworks (FastAPI, Django, Flask), databases (SQLAlchemy, psycopg, asyncpg), Redis, external HTTP calls, and AI/LLM libraries. Current version is 11.4.0 (Jan 2026). v12.0.0 released March 2026 with breaking removals.

pip install newrelic

Common errors

error newrelic-admin: not found ↓

cause The `newrelic-admin` wrapper script is not found in the system's PATH, or the New Relic Python agent is not installed in the currently active Python environment.

fix

Ensure the New Relic Python agent is installed in your application's virtual environment or system-wide, and that the newrelic-admin script (usually in bin/ or Scripts/ within your Python environment) is accessible via your system's PATH. You might need to activate your virtual environment or use its direct path.

error NEWRELIC: ... - New Relic could not start because the newrelic-admin script was called from a Python installation that is different from the Python installation that is currently running. ↓

cause This error occurs when the Python interpreter running the application differs from the Python interpreter used to run the `newrelic-admin` script, often seen in environments with multiple Python versions or virtual environments.

fix

Ensure that the newrelic-admin script and your application are executed using the *same* Python installation and virtual environment. This might involve explicitly calling the newrelic-admin script from the correct virtual environment's bin directory, e.g., /path/to/venv/bin/newrelic-admin run-program your_app.py.

error Initialization failed: Configuration has already been done against differing configuration file or environment. ↓

cause The New Relic Python agent's `newrelic.agent.initialize()` function was called multiple times with conflicting configuration parameters (different config files or environments), or conflicting environment variables/server-side configurations are present.

fix

Initialize the agent only once at the very beginning of your application's startup. Ensure consistency in configuration by using a single method (config file, environment variables, or newrelic.agent.initialize()) and avoiding conflicting settings across these methods. Environment variables override agent defaults, the config file overrides environment variables, and server-side config overrides the config file.

error ERROR - No license key was set in agent configuration. ↓

cause The New Relic Python agent cannot connect to the collector because the `license_key` is missing from the `newrelic.ini` configuration file or the `NEW_RELIC_LICENSE_KEY` environment variable is not set.

fix

Provide your New Relic license key either in the license_key setting within your newrelic.ini file or by setting the NEW_RELIC_LICENSE_KEY environment variable before your application starts.

error Python agent not reporting handled exceptions ↓

cause By default, the New Relic Python agent only reports *unhandled* exceptions that cause a transaction to end. Explicitly caught exceptions are not reported unless specifically instructed.

fix

To report handled exceptions, use newrelic.agent.notice_error() or newrelic.agent.record_exception() within your except blocks. These functions allow you to explicitly send exception details to New Relic APM.

Warnings

breaking initialize() must be called before ALL other imports. Placing it after framework or library imports silently disables instrumentation — no exception is raised, agent appears to load but instruments nothing. ↓

fix Use newrelic-admin run-program wrapper, or place initialize() as the first two lines of your entry point before any other import.

breaking Cross Application Tracing (CAT) fully removed in v12.0.0. Was deprecated since v7.0.0. Old tutorials and LLM-generated code using cross_application_tracer config keys will silently do nothing. ↓

fix Use Distributed Tracing (DT) instead. Remove cross_application_tracer settings from newrelic.ini.

breaking Python 3.8 support dropped in v12.0.0 (Python 3.8 EOL was Oct 2024). ↓

fix Pin to newrelic<12.0.0 if still on Python 3.8, or upgrade Python.

deprecated aioredis instrumentation deprecated. The aioredis package itself is abandoned. New Relic will remove this instrumentation in a future release. ↓

fix Use redis>=4.2 with redis.asyncio submodule. New Relic auto-instruments redis.asyncio.

deprecated Configuring agent via WSGI environ dictionary is deprecated. ↓

fix Use environment variables (NEW_RELIC_LICENSE_KEY, NEW_RELIC_APP_NAME, etc.) or newrelic.ini config file.

gotcha SSL certificates no longer bundled in v12.0.0. Environments without system CA certs (minimal Docker images) will fail to connect to New Relic. ↓

fix pip install newrelic[certificates]

breaking New Relic agent initialization failed because the specified configuration file (e.g., 'newrelic.ini') could not be found or was inaccessible. ↓

fix Ensure the configuration file is present in the current working directory, specified by an absolute path, or use environment variables for configuration (NEW_RELIC_LICENSE_KEY, NEW_RELIC_APP_NAME, etc.) or a newrelic.ini config file managed by the deployment.

breaking Calling `newrelic.agent.initialize(config_file)` requires the specified configuration file to exist and be accessible at the provided path. If the file is not found or cannot be read, a `newrelic.api.exceptions.ConfigurationError` will be raised. ↓

fix Ensure the 'newrelic.ini' configuration file is present in the application's working directory, or provide its absolute path to `newrelic.agent.initialize()`.

Install

newrelic-admin generate-config YOUR_LICENSE_KEY newrelic.ini

pip install newrelic[certificates]

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) newrelic - - 0.48s 24.2M

3.10 alpine (musl) certificates - - 0.48s 24.5M

3.10 slim (glibc) newrelic - - 0.34s 25M

3.10 slim (glibc) certificates - - 0.34s 25M

3.11 alpine (musl) newrelic - - 0.72s 27.2M

3.11 alpine (musl) certificates - - 0.73s 27.5M

3.11 slim (glibc) newrelic - - 0.59s 28M

3.11 slim (glibc) certificates - - 0.58s 28M

3.12 alpine (musl) newrelic - - 0.85s 18.8M

3.12 alpine (musl) certificates - - 0.84s 19.1M

3.12 slim (glibc) newrelic - - 0.82s 19M

3.12 slim (glibc) certificates - - 0.82s 20M

3.13 alpine (musl) newrelic - - 0.82s 18.5M

3.13 alpine (musl) certificates - - 0.85s 18.8M

3.13 slim (glibc) newrelic - - 0.78s 19M

3.13 slim (glibc) certificates - - 0.80s 19M

3.9 alpine (musl) newrelic - - 0.43s 23.7M

3.9 alpine (musl) certificates - - 0.45s 24.0M

3.9 slim (glibc) newrelic - - 0.39s 24M

3.9 slim (glibc) certificates - - 0.39s 25M

Imports

agent initialize

wrong

from fastapi import FastAPI
import newrelic.agent
newrelic.agent.initialize('newrelic.ini')  # too late — FastAPI already imported

correct

import newrelic.agent
newrelic.agent.initialize('newrelic.ini')  # MUST be first lines before any framework imports

initialize() must be called before ALL other library imports. Placing it after framework imports silently disables instrumentation with no error.

CLI runner (recommended)
wrong
```
gunicorn myapp.wsgi  # agent never loaded
```
correct
```
NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program gunicorn myapp.wsgi
```
newrelic-admin run-program is the safest init method — handles import ordering automatically.

Quickstart stale last tested: 2026-04-23

Agent initialization patterns. CLI wrapper is preferred. Manual init requires initialize() before all other imports.

# Option 1: CLI wrapper (recommended — handles ordering automatically)
# NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program gunicorn myapp.wsgi

# Option 2: Manual init — must be absolute first lines of entry point
import newrelic.agent
newrelic.agent.initialize('newrelic.ini')

# Framework imports AFTER initialize()
from fastapi import FastAPI
app = FastAPI()