Prometheus Client

0.24.1 verified Tue May 12 auth: no python install: verified quickstart: stale

Python client for the Prometheus monitoring system, currently at version 0.24.1. It is actively maintained with frequent updates for enhancements and bug fixes.

pip install prometheus-client

Common errors

error ModuleNotFoundError: No module named 'prometheus_client' ↓

cause This error occurs when the `prometheus-client` library is not installed, not installed in the active Python environment, or imported incorrectly. A common mistake is trying to import `prometheus.client` instead of `prometheus_client`.

fix

Ensure the library is installed using pip install prometheus-client and then import it correctly using import prometheus_client or from prometheus_client import ...

error AttributeError: 'Gauge' object has no attribute 'labels' ↓

cause This error typically arises when attempting to access a `.labels()` method directly on a metric object (like a `Gauge` or `Counter`) that was created without specifying label names in its constructor. Labels must be defined when the metric is initialized to allow setting their values later.

fix

When creating the metric, define the label names as a list of strings. Then, to set label values, call the .labels() method with the corresponding values. For example: my_gauge = Gauge('my_gauge', 'Description', ['label_name']) and then my_gauge.labels('value').set(10)

error ValueError: Duplicated timeseries in CollectorRegistry ↓

error Collector already registered that provides name: <metric_name> ↓

cause This error indicates that you are attempting to register a metric with the same name multiple times within the same `CollectorRegistry`. Prometheus metrics must have unique names within a registry. This often happens when metrics are defined globally and imported multiple times, or when a function creating metrics is called repeatedly.

fix

Ensure each metric is registered only once. Define metrics at the module level or use a pattern to prevent re-registration, especially in tests or applications with hot-reloading. You can pass a specific registry to the metric constructor to avoid interfering with the default global registry. For example: my_gauge = Gauge('my_unique_gauge_name', 'Help text') (defined once) or use REGISTRY.unregister(metric) for testing scenarios, though it's generally discouraged in production.

error OSError: [Errno 98] Address already in use ↓

cause This error occurs when `prometheus_client.start_http_server()` is called, but the specified port is already in use by another process on the system.

fix

Change the port number passed to start_http_server() to an available one, or identify and terminate the process currently using the desired port. You can use OS commands like netstat -tulnp | grep <port> (Linux) or lsof -i :<port> (macOS) to find the offending process.

Warnings

breaking Breaking changes in HTTP method validation introduced in v0.21.0. ↓

fix Ensure your HTTP methods conform to GET or OPTIONS to avoid requests being rejected.

gotcha Incorrect usage of CollectorRegistry may lead to metrics not appearing. ↓

fix Always create and use a CollectorRegistry instance for metric registration.

gotcha A timeout occurred during test execution, indicating a potential long-running operation, deadlock, or resource exhaustion. ↓

fix Investigate application logs, system metrics, and resource usage for the tests. Consider increasing timeouts, optimizing code, or checking for infinite loops/deadlocks.

breaking The test timed out, indicating a potential infinite loop, deadlock, or an exceptionally long-running operation. ↓

fix Investigate the application's execution flow for potential deadlocks, infinite loops, or resource contention that could cause extended execution times.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.21s 18.3M

3.10 slim (glibc) - - 0.18s 19M

3.11 alpine (musl) - - 0.30s 20.3M

3.11 slim (glibc) - - 0.27s 21M

3.12 alpine (musl) - - 0.23s 12.1M

3.12 slim (glibc) - - 0.24s 13M

3.13 alpine (musl) - - 0.23s 11.7M

3.13 slim (glibc) - - 0.23s 12M

3.9 alpine (musl) - - 0.17s 17.8M

3.9 slim (glibc) - - 0.15s 18M

Imports

CollectorRegistry
```
from prometheus_client import CollectorRegistry
```
Ensure you import from prometheus_client, not any incorrect paths.

Quickstart stale last tested: 2026-04-23

Start a Prometheus server on port 8000.

from prometheus_client import start_http_server, CollectorRegistry
import time

registry = CollectorRegistry()
start_http_server(8000)
while True:
    time.sleep(1)