Install & Compatibility
Where this runs
tested against v? · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.044s · 65.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.036s · 137MB
101MB installed
● package 101MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
StatsClient
✓ from statsd import StatsClient
This quickstart demonstrates how to initialize a StatsD client and send common metric types: counters, timers, and gauges. It uses environment variables for host and port for easy configuration, defaulting to localhost:8125. A prefix is added to all metrics for better organization.
import statsd
import os
# Configure StatsD client, typically pointing to a local StatsD agent
# Default host is 'localhost', default port is 8125
# You can override with environment variables or direct arguments
statsd_host = os.environ.get('STATSD_HOST', 'localhost')
statsd_port = int(os.environ.get('STATSD_PORT', 8125))
c = statsd.StatsClient(host=statsd_host, port=statsd_port, prefix='my_app')
# Increment a counter
c.incr('page_views')
c.incr('successful_requests', 5)
# Record a timing (in milliseconds)
import time
start_time = time.time()
time.sleep(0.05) # Simulate work
duration_ms = (time.time() - start_time) * 1000
c.timing('api_response_time', duration_ms)
# Set a gauge value
c.gauge('current_users', 150)
print(f"Sent metrics to StatsD at {statsd_host}:{statsd_port}")
print("Check your StatsD server/Graphite for 'my_app.page_views', 'my_app.successful_requests', 'my_app.api_response_time', 'my_app.current_users'")
Debug
Known issues
breakingThe PyPI package `python-statsd` has effectively been replaced by `statsd` (maintained by `jsocol/pystatsd`). While `WoLpH/python-statsd` GitHub repo lists version 2.1.0, its own documentation links point to the `statsd` package (currently 4.0.1). Installing `python-statsd` via pip today will install the `statsd` package.fixUse `pip install statsd`. Ensure your code uses `from statsd import StatsClient`. If you specifically need features from older `python-statsd` (2.x), verify its API is compatible or find an archived version.
affects: <4.0.0 (for old `python-statsd`)
gotchaThis library (`statsd` on PyPI) explicitly does not support tagged metrics (e.g., `metric:value|#tag1:foo,tag2:bar`) used by systems like Datadog, Telegraf, or Prometheus StatsD exporters. Attempting to send tags will result in data loss or incorrect metric names.fixIf you require tagged metrics, consider alternative Python StatsD clients like `dogstatsd-python` or `statsd-exporter`, or adjust your metric naming strategy to encode tags into the metric name itself (e.g., `my_metric.foo.bar`).
affects: All versions of `statsd` (PyPI package)
gotchaStatsD primarily uses UDP for metric transmission, which is a 'fire-and-forget' protocol. While highly performant, it does not guarantee delivery. Packets can be silently dropped by the network or the StatsD server under heavy load or network issues.fixFor critical metrics where delivery is paramount, consider using a StatsD server and client that support TCP (if available in your setup) or explore other monitoring solutions designed for guaranteed delivery. For standard use, acknowledge the UDP trade-off and monitor your StatsD server for dropped packets.
affects: All versions
gotchaSeveral Python libraries exist on PyPI with 'statsd' in their name (e.g., `statsd`, `statsd-client`, `statsd-exporter`, `statsd-tags`). This can lead to confusion and accidentally installing a different client with a non-compatible API or missing features.fixAlways explicitly `pip install statsd` (for this library). Verify your `import statsd` correctly brings in the `StatsClient` class, and consult the documentation for the specific client you intend to use.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'python_statsd'
The user is attempting to import a package named `python_statsd`, but the correct and actively maintained package on PyPI is named `statsd`.
fixInstall the correct package using `pip install statsd` and update the import statement in your code to `import statsd`.
AttributeError: 'StatsClient' object has no attribute 'count'
The `statsd` library uses `incr` and `decr` methods for incrementing and decrementing counters, not a method named `count` or `counter`.
fixUse `client.incr('metric_name')` or `client.decr('metric_name')` to update counters. TypeError: __init__() missing 1 required positional argument: 'host'
The `StatsClient` class constructor requires at least the StatsD server's hostname as its first argument.
fixInitialize the `StatsClient` with the target host and optionally the port, for example: `c = statsd.StatsClient('localhost', 8125)`. Upgrade
Version history
2.1.0latest on PyPI · released Sep 5, 2017
Audit
Dependencies
No dependency data recorded yet.