Datadog Python Library (datadogpy)

0.52.1 verified Tue May 12 auth: no python install: verified quickstart: verified

The `datadog` Python library (`datadogpy`) provides convenient interfaces for interacting with Datadog's HTTP API and sending metrics, events, and service checks via DogStatsD. It supports both UDP and Unix Domain Socket (UDS) transports for DogStatsD and includes a CLI tool ('dog') for API operations. As of version 0.52.1, it continues to be actively maintained, focusing on core API interactions and DogStatsD client functionality.

pip install datadog

Common errors

error ModuleNotFoundError: No module named 'datadog' ↓

cause The `datadog` Python package is not installed in your current environment.

fix

Run pip install datadog to install the library.

error AttributeError: module 'datadog' has no attribute 'statsd' ↓

cause A local Python file named `datadog.py` (or a similar name) is shadowing the installed `datadog` library, causing the Python interpreter to import your local file instead of the actual package.

fix

Rename your local Python file (e.g., from datadog.py to my_datadog_script.py) to avoid the naming conflict.

error datadog.api.exceptions.ApiNotInitialized: No API key is set ↓

cause The Datadog API and/or Application keys have not been properly provided to the `datadog.initialize()` function or set as environment variables.

fix

Initialize the library by calling datadog.initialize(api_key='YOUR_API_KEY', app_key='YOUR_APP_KEY') with valid keys, or set the DATADOG_API_KEY and DATADOG_APP_KEY environment variables.

error ConnectionRefusedError: [Errno 111] Connection refused (when sending DogStatsD metrics) ↓

cause The Datadog Agent's DogStatsD server is either not running, not accessible at the specified host/port, or is configured to only accept local traffic from the agent itself.

fix

Ensure the Datadog Agent is running and its DogStatsD server is active (default UDP port 8125). Verify the statsd_host and statsd_port parameters in your datadog.initialize() call. If running your application on a different host than the Agent, ensure dogstatsd_non_local_traffic: true is set in your Datadog Agent configuration.

error AssertionError: Datadog API key is not set ↓

cause Datadog API methods were called without initializing the library with an API key, or without setting the DATADOG_API_KEY environment variable.

fix

datadog.initialize(api_key='YOUR_API_KEY', app_key='YOUR_APP_KEY') or set DATADOG_API_KEY and DATADOG_APP_KEY environment variables.

Warnings

gotcha Confusion between `datadog` and `datadog-api-client` libraries. `datadog` (this library) is the older, more general client. `datadog-api-client` is a newer, generated client providing comprehensive access to all Datadog API endpoints (including v2 and async capabilities). They have different installation paths (`pip install datadog` vs `pip install datadog-api-client`) and import patterns (`from datadog import ...` vs `from datadog_api_client import ...`). Ensure you install and import the correct library for your needs. ↓

fix Always check which library you need. If you need v2 API access, async support, or access to all new endpoints, `datadog-api-client` is generally preferred. For simpler v1 API interactions or DogStatsD, `datadog` is sufficient.

gotcha API and Application Keys are critical for authentication. For API interactions (e.g., `api.Event.create`), both an API key and an Application key are almost always required. ↓

fix Initialize the client using `datadog.initialize(api_key="YOUR_API_KEY", app_key="YOUR_APP_KEY")` or, preferably, set environment variables `DATADOG_API_KEY` and `DATADOG_APP_KEY`. Never hardcode keys directly in production code.

gotcha Regional endpoints must be configured for non-US Datadog accounts. If your Datadog instance is in the EU, for example, the default API host will be incorrect. ↓

fix Pass `api_host='https://api.datadoghq.eu'` (or your specific region's host) to `datadog.initialize()` or set the `DATADOG_HOST` environment variable.

gotcha DogStatsD metrics require a running Datadog Agent. The `datadog.statsd` client sends UDP packets to a local DogStatsD server (usually part of the Datadog Agent). If the Agent is not running or not accessible on the configured host/port, metrics will be dropped silently or fail. ↓

fix Ensure the Datadog Agent is installed, running, and configured to receive DogStatsD metrics (default port 8125). Verify network reachability from your application to the Agent.

gotcha This `datadog` library does not provide APM (Application Performance Monitoring) tracing and profiling functionality. That is handled by the separate `ddtrace` library. ↓

fix For distributed tracing, continuous profiling, and auto-instrumentation of frameworks (e.g., Flask, Django), install and use the `ddtrace` library (`pip install ddtrace`).

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.72s 22.3M

3.10 slim (glibc) - - 0.53s 23M

3.11 alpine (musl) - - 0.89s 24.6M

3.11 slim (glibc) - - 0.72s 25M

3.12 alpine (musl) - - 0.79s 16.3M

3.12 slim (glibc) - - 0.78s 17M

3.13 alpine (musl) - - 0.77s 16.0M

3.13 slim (glibc) - - 0.79s 16M

3.9 alpine (musl) - - 0.68s 21.6M

3.9 slim (glibc) - - 0.60s 22M

Imports

initialize
```
from datadog import initialize
```
Used to configure API/App keys and other client settings.
api
```
from datadog import api
```
Provides access to Datadog's HTTP API endpoints (e.g., Events, Metrics).
statsd
```
from datadog import statsd
```
Provides a client for sending metrics via DogStatsD to the Datadog Agent.
ThreadStats
```
from datadog import ThreadStats
```
An alternative client for collecting and flushing metrics via the Datadog REST API in a worker thread.
ApiClient
wrong
```
from datadog import ApiClient
```
correct
```
from datadog_api_client import ApiClient
```
This library (`datadog`) is distinct from `datadog-api-client`, which is a separately installed, generated client for all Datadog API endpoints (including v2, async support, etc.). Do not confuse their imports.

Quickstart verified last tested: 2026-04-23

This quickstart demonstrates how to initialize the Datadog client using environment variables for API and Application keys and then send both an event via the HTTP API and custom metrics via DogStatsD. Remember to have the Datadog Agent running for DogStatsD metrics.

import os
from datadog import initialize, api, statsd

# Configure with API and App keys, preferably from environment variables
options = {
    'api_key': os.environ.get('DD_API_KEY', 'YOUR_DATADOG_API_KEY'),
    'app_key': os.environ.get('DD_APP_KEY', 'YOUR_DATADOG_APP_KEY'),
    # Uncomment and set api_host if your Datadog account is outside the US (e.g., EU)
    # 'api_host': 'https://api.datadoghq.eu'
}
initialize(**options)

# Send an event to the Datadog Event Stream
try:
    title = "Python Quickstart Event!"
    text = "This is a test event sent from the datadog Python library."
    tags = ["env:dev", "service:my-app", "source:python-script"]
    response = api.Event.create(title=title, text=text, tags=tags)
    print(f"Event sent successfully: {response.get('status')}. Event ID: {response.get('event', {}).get('id')}")
except Exception as e:
    print(f"Error sending event: {e}")

# Send a custom metric via DogStatsD (requires Datadog Agent running)
try:
    statsd.increment('my_app.page_views', tags=['page:home', 'version:1.0'])
    statsd.gauge('my_app.users_online', 150, tags=['region:us-east'])
    print("Metrics sent via DogStatsD.")
except Exception as e:
    print(f"Error sending metrics via DogStatsD: {e}")