{"id":195,"library":"newrelic","title":"New Relic Python Agent","description":"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.","status":"active","version":"11.4.0","language":"python","source_language":"en","source_url":"https://docs.newrelic.com/docs/release-notes/agent-release-notes/python-release-notes/","tags":["observability","apm","monitoring","tracing","instrumentation"],"install":[{"cmd":"pip install newrelic","lang":"bash","label":"Python (agent)"},{"cmd":"newrelic-admin generate-config YOUR_LICENSE_KEY newrelic.ini","lang":"bash","label":"Generate config file"},{"cmd":"pip install newrelic[certificates]","lang":"bash","label":"Python (with bundled SSL certs, required in v12+)"}],"dependencies":[{"reason":"SSL certificates no longer bundled in v12.0.0. Required in environments without system certs.","package":"newrelic[certificates]","optional":true}],"imports":[{"note":"initialize() must be called before ALL other library imports. Placing it after framework imports silently disables instrumentation with no error.","wrong":"from fastapi import FastAPI\nimport newrelic.agent\nnewrelic.agent.initialize('newrelic.ini')  # too late — FastAPI already imported","symbol":"agent initialize","correct":"import newrelic.agent\nnewrelic.agent.initialize('newrelic.ini')  # MUST be first lines before any framework imports"},{"note":"newrelic-admin run-program is the safest init method — handles import ordering automatically.","wrong":"gunicorn myapp.wsgi  # agent never loaded","symbol":"CLI runner (recommended)","correct":"NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program gunicorn myapp.wsgi"}],"quickstart":{"code":"# Option 1: CLI wrapper (recommended — handles ordering automatically)\n# NEW_RELIC_CONFIG_FILE=newrelic.ini newrelic-admin run-program gunicorn myapp.wsgi\n\n# Option 2: Manual init — must be absolute first lines of entry point\nimport newrelic.agent\nnewrelic.agent.initialize('newrelic.ini')\n\n# Framework imports AFTER initialize()\nfrom fastapi import FastAPI\napp = FastAPI()","lang":"python","description":"Agent initialization patterns. CLI wrapper is preferred. Manual init requires initialize() before all other imports."},"warnings":[{"fix":"Use newrelic-admin run-program wrapper, or place initialize() as the first two lines of your entry point before any other import.","message":"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.","severity":"breaking","affected_versions":"all"},{"fix":"Use Distributed Tracing (DT) instead. Remove cross_application_tracer settings from newrelic.ini.","message":"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.","severity":"breaking","affected_versions":"< 12.0.0"},{"fix":"Pin to newrelic<12.0.0 if still on Python 3.8, or upgrade Python.","message":"Python 3.8 support dropped in v12.0.0 (Python 3.8 EOL was Oct 2024).","severity":"breaking","affected_versions":"< 12.0.0"},{"fix":"Use redis>=4.2 with redis.asyncio submodule. New Relic auto-instruments redis.asyncio.","message":"aioredis instrumentation deprecated. The aioredis package itself is abandoned. New Relic will remove this instrumentation in a future release.","severity":"deprecated","affected_versions":"all"},{"fix":"Use environment variables (NEW_RELIC_LICENSE_KEY, NEW_RELIC_APP_NAME, etc.) or newrelic.ini config file.","message":"Configuring agent via WSGI environ dictionary is deprecated.","severity":"deprecated","affected_versions":"all"},{"fix":"pip install newrelic[certificates]","message":"SSL certificates no longer bundled in v12.0.0. Environments without system CA certs (minimal Docker images) will fail to connect to New Relic.","severity":"gotcha","affected_versions":">= 12.0.0"},{"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.","message":"New Relic agent initialization failed because the specified configuration file (e.g., 'newrelic.ini') could not be found or was inaccessible.","severity":"breaking","affected_versions":"all"},{"fix":"Ensure the 'newrelic.ini' configuration file is present in the application's working directory, or provide its absolute path to `newrelic.agent.initialize()`.","message":"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.","severity":"breaking","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T09:58:02.453Z","next_check":"2026-06-25T00:00:00.000Z","problems":[{"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.","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.","error":"newrelic-admin: not found"},{"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`.","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.","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."},{"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.","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.","error":"Initialization failed: Configuration has already been done against differing configuration file or environment."},{"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.","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.","error":"ERROR - No license key was set in agent configuration."},{"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.","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.","error":"Python agent not reporting handled exceptions"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.48,"mem_mb":12.5,"disk_size":"24.2M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"certificates","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.48,"mem_mb":12.5,"disk_size":"24.5M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.34,"mem_mb":12.5,"disk_size":"25M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"certificates","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.34,"mem_mb":12.5,"disk_size":"25M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.72,"mem_mb":14.4,"disk_size":"27.2M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"certificates","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.73,"mem_mb":14.4,"disk_size":"27.5M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.59,"mem_mb":14.4,"disk_size":"28M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"certificates","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.58,"mem_mb":14.4,"disk_size":"28M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.85,"mem_mb":15.7,"disk_size":"18.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"certificates","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.84,"mem_mb":15.7,"disk_size":"19.1M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.82,"mem_mb":15.7,"disk_size":"19M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"certificates","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.82,"mem_mb":15.7,"disk_size":"20M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.82,"mem_mb":16.5,"disk_size":"18.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"certificates","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.85,"mem_mb":16.5,"disk_size":"18.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.78,"mem_mb":16.5,"disk_size":"19M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"certificates","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.8,"mem_mb":16.5,"disk_size":"19M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.43,"mem_mb":12.1,"disk_size":"23.7M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"certificates","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.45,"mem_mb":12.1,"disk_size":"24.0M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.39,"mem_mb":12.1,"disk_size":"24M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"certificates","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.39,"mem_mb":12.1,"disk_size":"25M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}