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.
Install & Compatibility
Where this runs
tested against v0.52.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.774s · 22.3MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 2.2s · import 0.684s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
✓ from datadog_api_client import ApiClient
✗ from datadog 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.
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}")
dog --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'datadog'
The `datadog` Python package is not installed in your current environment.
fixRun `pip install datadog` to install the library.
AttributeError: module 'datadog' has no attribute 'statsd'
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.
fixRename your local Python file (e.g., from `datadog.py` to `my_datadog_script.py`) to avoid the naming conflict.
datadog.api.exceptions.ApiNotInitialized: No API key is set
The Datadog API and/or Application keys have not been properly provided to the `datadog.initialize()` function or set as environment variables.
fixInitialize 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.
ConnectionRefusedError: [Errno 111] Connection refused (when sending DogStatsD metrics)
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.
fixEnsure 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.
AssertionError: Datadog API key is not set
Datadog API methods were called without initializing the library with an API key, or without setting the DATADOG_API_KEY environment variable.
fixdatadog.initialize(api_key='YOUR_API_KEY', app_key='YOUR_APP_KEY') or set DATADOG_API_KEY and DATADOG_APP_KEY environment variables.
Audit
Dependencies
pythonrequiredRequires Python 2.7 or >=3.6, but modern use strongly recommends Python 3.7+ for compatibility and features.