histoprint

library2.7.1pypypi✓ verified 22d ago

histoprint is a Python library that provides pretty-printing of NumPy (and other compatible) histograms directly to the console. It leverages terminal color codes and Unicode characters to create visually appealing histogram representations. Currently at version 2.6.0, it follows a regular release cadence with updates typically adding features, improving compatibility, and addressing minor issues.

data serialization

pip install histoprint

github ↗package ↗

INSTALL

IMPORT

SIG · HISTOPRINT

histoprint

datapythonv2.7.1

Install

5.0s avg

Import

251ms

Disk

93MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.7.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

musl

py 3.10–3.915 runs

installs and imports cleanly · install 0.0s · import 0.239s · 91MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 5.0s · import 0.263s · 87MB

93MB installed

● package 93MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

text_hist

✓ from histoprint import text_hist

print_hist

✓ from histoprint import print_hist

This quickstart demonstrates how to generate sample data using NumPy and then visualize it as histograms in the console using `histoprint.text_hist` for single-array input and `histoprint.print_hist` for displaying multiple or pre-computed NumPy histograms, including stacked visualizations.

import numpy as np from histoprint import text_hist, print_hist # Create some sample data A = np.random.randn(1000) - 2 B = np.random.randn(1000) C = np.random.randn(1000) + 2 # Use text_hist for a single array (wraps numpy.histogram) print('--- Single Histogram (text_hist) ---') text_hist(B, bins=[-5, -3, -2, -1, -0.5, 0, 0.5, 1, 2, 3, 5], title="Variable bin widths") # Create NumPy histograms manually for print_hist histA = np.histogram(A, bins=15, range=(-5, 5)) histB = np.histogram(B, bins=15, range=(-5, 5)) histC = np.histogram(C, bins=15, range=(-5, 5)) # print_hist can print multiple histograms at once print('\n--- Overlapping Histograms (print_hist) ---') print_hist(([histA[0], histB[0], histC[0]], histA[1]), title="Overlays", labels="ABC") print('\n--- Stacked Histograms (print_hist) ---') print_hist(([histA[0], histB[0], histC[0]], histA[1]), title="Stacks", stack=True, labels="ABC", bg_colors="rgb")

histoprint --version

Debug

Known issues

breakingVersion 2.0.0 dropped support for Python 2.7 and Python 3.5. Ensure your environment uses Python 3.6 or newer (Python 3.8+ recommended for v2.6.0+).

fix

Upgrade your Python environment to 3.8 or later.

affects: >=2.0.0

breakingThe optional extra dependency 'root' was renamed to 'uproot' in version 2.3.0. If you were installing with `pip install histoprint[root]`, you must now use `pip install histoprint[uproot]`.

fix

Change install command from `histoprint[root]` to `histoprint[uproot]`.

affects: >=2.3.0

breakingVersion 2.6.0 and later explicitly require Python 3.8+. Previous versions supported Python 3.6+.

fix

Ensure your Python environment is version 3.8 or higher.

affects: >=2.6.0

gotchaSome terminals may not correctly display Unicode combining characters used by histoprint for overlaying histograms. If output appears garbled, you may need to constrain the character set.

fix

Consult histoprint documentation for options to disable or limit Unicode combining characters, such as `symbols` argument in `print_hist` or specific configuration settings if available.

affects: All

gotchaWhile `text_hist` accepts raw data, `print_hist` expects a tuple of `(counts, bin_edges)` similar to the output of `numpy.histogram` or a compatible `PlottableHistogram` object (e.g., from `boost-histogram` or `Hist` library).

fix

Always pass pre-computed histogram data (counts and bin edges) to `print_hist` or ensure the object adheres to the `PlottableProtocol`.

affects: All

Errors

Common errors & fixes

histoprint characters garbled in terminal

Your terminal emulator may not fully support Unicode combining characters or certain ANSI color codes used by histoprint for rich visual output. Instead of a Python error, this manifests as visual artifacts or incorrect display.

fix

To fix this, you can instruct histoprint to use a simpler set of symbols or disable colors. For example, pass `symbols='|= '` to `print_hist` or `text_hist` to avoid combining characters, or adjust your terminal's font or settings if it supports better Unicode rendering.

NameError: name 'text_hist' is not defined

This error occurs when you try to use `text_hist` (or `print_hist`) without explicitly importing it from the `histoprint` library.

fix

Add the import statement `from histoprint import text_hist` (or `from histoprint import print_hist` for `print_hist`) at the beginning of your Python script or interactive session.

TypeError: object of type 'numpy.ndarray' has no len()

The `histoprint` functions, such as `print_hist`, expect a pre-computed NumPy histogram as input, which is typically a tuple `(counts, bin_edges)`. This error occurs if you pass raw data (e.g., a single NumPy array) directly instead of a processed histogram.

fix

First, compute the histogram using `numpy.histogram()` with your data and desired bins, then pass the resulting tuple to `histoprint.print_hist()` or `histoprint.text_hist()`. For example: `hist_data = np.histogram(my_data, bins=10); histoprint.print_hist(hist_data)`.

AttributeError: module 'histoprint' has no attribute 'hist'

You are attempting to call a non-existent method named `hist()` directly on the `histoprint` module. Developers sometimes make this mistake when accustomed to other plotting libraries (like Matplotlib) that expose a `hist()` function directly.

fix

Use the correct functions provided by `histoprint` for printing histograms, which are `histoprint.text_hist()` for simple histograms or `histoprint.print_hist()` for more advanced options, including multiple histograms and overlays.

Upgrade

Version history

2.7.1latest on PyPI · released Aug 17, 2026

Audit

Dependencies

numpyrequiredCore functionality relies on NumPy arrays for histogram data.

uprootoptionalOptional dependency for plotting ROOT files via the CLI and PlottableProtocol-like histograms.

richoptionalOptional dependency for enhanced console output, particularly for RichHistogram class.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/scikit-hep/histoprint ↗

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