---
id: hdrhistogram
version: "0.10.7"
license: unclear
license_treatment: permissive
maintenance: active
---

# hdrhistogram — High Dynamic Range histogram in native python

License: permissive · Maintenance: active · Downloads: 551.5K/mo

## What it is and what it does

hdrhistogram is a Python port of the Java HDR Histogram library, designed to record and analyze latency and performance distributions with high precision across a wide dynamic range. It solves the problem of accurately capturing percentile-based performance metrics without the memory overhead of storing every individual measurement; instead, it uses a bucketing strategy that trades a small, controlled amount of precision for dramatic space efficiency.

The package supports recording values with optional correction for coordinated omission (a common measurement bias in latency testing), querying percentiles and statistical summaries, iterating over recorded values in multiple ways, and serializing histograms to portable formats for storage or cross-platform analysis. It includes a command-line tool (dump_hdrh) for inspecting encoded histograms and supports 16-bit, 32-bit, and 64-bit counters. Runtime dependencies are minimal (pbr and setuptools for build support).

Use it for:

- Track API response latencies in production and analyze tail percentiles (p99, p99.9) without storing every request.
- Measure and compare performance distributions across multiple services or time windows by encoding histograms as portable blobs.
- Correct for coordinated omission bias when benchmarking systems under load, ensuring accurate latency reporting.
- Generate percentile distribution tables in .hgrm format for plotting and reporting performance characteristics.
- Aggregate histograms from distributed systems into a central histogram for unified performance analysis.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Records and analyzes high-precision latency and performance distributions using HDR Histogram, a data structure optimized for capturing value ranges with controlled precision loss.

Yes. hdrhistogram is actively maintained, has no known vulnerabilities, and fills a specific need for efficient, precise latency distribution tracking. Install it if you need percentile-based performance analysis or are porting HDR Histogram code from Java or C. The prebuilt wheels make installation straightforward on common platforms; only consider friction if you're on an unsupported architecture.

## Install

pip install hdrhistogram
uv add hdrhistogram
poetry add hdrhistogram

## Installing hdrhistogram

Before you install: Medium install friction due to C extension compilation fallback, though prebuilt wheels cover Linux, macOS, and Windows for Python 3.10–3.14. Active maintenance with recent release (66 days old) and no known vulnerabilities.

License in practice: Licensed under Apache Software License (permissive), allowing commercial and private use with minimal restrictions.

Quickstart:

pip install hdrhistogram

from hdrhistogram import HdrHistogram

histogram = HdrHistogram(1, 3600000, 2)
histogram.record_value(latency)
percentile_99_9 = histogram.get_value_at_percentile(99.9)

Requires Python 3.10 or later; C compiler needed only if no prebuilt wheel matches your platform.

Verify before relying:

- Whether the package's coordinated omission correction is suitable for your specific measurement scenario.
- Performance characteristics and memory overhead when recording millions of values.
- Interoperability guarantees with Java and C HDR Histogram versions beyond V2 format.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 551.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

latency histogram recording, high dynamic range histogram, percentile analysis, performance distribution tracking, hdr histogram python, coordinated omission correction, histogram serialization, performance-monitoring, latency-analysis, metrics

[View on SkillFed](https://skillfed.io/packages/hdrhistogram) · [View on PyPI](https://pypi.org/project/hdrhistogram/)