hepunits

library2.4.6pypypi✓ verified 22d ago

hepunits is a Python library that provides a comprehensive set of units and physical constants specifically tailored for the High Energy Physics (HEP) system of units. It simplifies working with quantities in HEP research by offering well-defined units like MeV and constants such as the speed of light. The library is actively maintained, with regular updates for Python version compatibility and minor feature enhancements, currently at version 2.4.4.

data serialization

pip install hepunits

github ↗package ↗

INSTALL

IMPORT

SIG · HEPUNITS

hepunits

datapythonv2.4.6

Install

1.5s avg

Import

10ms

Disk

16MB

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.4.6 · 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.910 runs

installs and imports cleanly · install 0.0s · import 0.002s · 17.9MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.5s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

units

✓ from hepunits import units

✗ from hepunits.units import units

Importing 'units' directly from the top-level package is the idiomatic way to access unit definitions. The submodule 'hepunits.units' is implicitly exposed via the top-level 'units' object, so 'from hepunits.units import units' creates a redundant nesting (e.g., 'units.units.GeV').

constants

✓ from hepunits import constants

get_unit_registry

✓ import hepunits.pint; ureg = hepunits.pint.get_unit_registry()

✗ from hepunits.pint import get_unit_registry

While 'from hepunits.pint import get_unit_registry' technically works, the recommended pattern for using the Pint integration is to import the 'hepunits.pint' module directly to keep it clear that Pint functionality is being accessed through the hepunits wrapper.

This example demonstrates how to import and use units and physical constants. It also shows the optional integration with the Pint library for more advanced quantity handling, which requires installing `hepunits[pint]`.

from hepunits import units, constants # Accessing units energy = 100 * units.GeV print(f"Energy: {energy}") # Accessing constants speed_of_light = constants.c_light print(f"Speed of light: {speed_of_light} in mm/ns") # Using Pint integration (requires pip install hepunits[pint]) try: import hepunits.pint ureg = hepunits.pint.get_unit_registry() mass = 938.27 * ureg.MeV / ureg.c**2 print(f"Proton mass (Pint): {mass}") except ImportError: print("Pint integration not installed. Skipping Pint example.")

Debug

Known issues

breakingPython version support is frequently updated. For example, Python 3.8 support was removed in v2.4.3, and Python 3.7 support was removed in v2.3.4. Always check `requires_python` in `pyproject.toml` or `setup.py` for your target version.

fix

Ensure your Python environment meets the minimum `requires_python` specified for the `hepunits` version you are using. Upgrade Python if necessary.

affects: >=2.3.4

gotchaThe `Pint` integration for unit-aware quantity objects is optional and requires `pip install hepunits[pint]`. If you attempt to use `hepunits.pint` functionality without installing the extra dependency, you will encounter an `ImportError`.

fix

Install `hepunits` with the `pint` extra: `pip install hepunits[pint]`.

affects: >=2.4.0

gotchahepunits is based on the High Energy Physics (HEP) system of units, where common units like energy are in MeV and length in mm, and constants like the speed of light are defined accordingly (e.g., `c_light` is in mm/ns). This differs from standard SI, which can lead to unexpected results if not accounted for.

fix

Always be mindful of the specific unit system (HEP) that hepunits employs. Convert to or from other unit systems explicitly when interacting with external libraries or data not using HEP units.

affects: *

gotchaUnit and constant objects (e.g., `units.GeV`, `constants.c_light`) are not themselves `Pint` Quantities unless you explicitly use the `hepunits.pint` integration and its unit registry. Basic unit access provides bare numeric values when multiplied or divided.

fix

If you require unit-aware arithmetic and type safety, use the `hepunits.pint` integration by importing the `hepunits.pint` module and obtaining its unit registry.

affects: *

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'hepunits'

The `hepunits` package has not been installed in your current Python environment.

fix

pip install hepunits

TypeError: Cannot convert <value> to pint.Quantity. Missing unit.

You are attempting to perform an arithmetic operation (like addition or subtraction) between a dimensionless Python number (int/float) and a `hepunits` Quantity without explicitly assigning units to the number.

fix

Ensure both operands have compatible units, for example: `energy = 10 * hepunits.GeV; total_energy = energy + 5 * hepunits.GeV`

ImportError: cannot import name 'c' from 'hepunits.units'

You are trying to import a physical constant (like 'c' for speed of light) from the `hepunits.units` submodule, but constants reside in `hepunits.constants`.

fix

Import constants from `hepunits.constants`, or access them directly from the top-level `hepunits` module: `from hepunits.constants import c` or `import hepunits; speed_of_light = hepunits.c`

Upgrade

Version history

2.4.6latest on PyPI · released Jun 16, 2026

Audit

Dependencies

pintoptionalOptional integration for unit conversions and quantity objects.

Agent activity

13 hits · last 30 days

node

Resources

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

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