New Relic Python Agent

11.4.0 · active · verified Wed Mar 25

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.

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]

Install

pip install newrelic Python (agent)
newrelic-admin generate-config YOUR_LICENSE_KEY newrelic.ini Generate config file
pip install newrelic[certificates] Python (with bundled SSL certs, required in v12+)

Imports

agent initialize
```
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)
```
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

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()

view raw JSON →