datadog

library0.53.0pypypi✓ verified 29d ago

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.

observability

pip install datadog

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · DATADOG

datadog

observabilitypythonv0.53.0

Install

2.5s avg

Import

450ms

Disk

21MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.53.0 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.466s · 22.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.5s · import 0.434s · 23MB

21MB installed

● package 21MB

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

Debug

Known issues

gotchaConfusion 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.

affects: All versions

gotchaAPI 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.

affects: All versions

gotchaRegional 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.

affects: All versions

gotchaDogStatsD 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.

affects: All versions

gotchaThis `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`).

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'datadog'

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

fix

Run `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.

fix

Rename 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.

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.

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.

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.

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.

fix

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

Upgrade

Version history

0.53.0latest on PyPI · released Jul 24, 2026

Audit

Dependencies

pythonrequiredRequires Python 2.7 or >=3.6, but modern use strongly recommends Python 3.7+ for compatibility and features.

Agent activity

33 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/DataDog/datadogpy ↗

packagehttps://pypi.org/project/datadog/ ↗

homepagehttps://www.datadoghq.com ↗

docshttps://datadogpy.readthedocs.io/en/latest/ ↗