Install & Compatibility
Where this runs
tested against v3.1.0 · 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.920 runs
installs and imports cleanly · install 0.0s · import 2.030s · 151.7MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 8.4s · import 1.901s · 148MB
164MB installed
● package 164MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
unyt_array
✓ from unyt import unyt_array
✗ import unyt_array # Directly importing from unyt_array submodule is not standard
Most common units and functions are exposed directly in the top-level 'unyt' namespace.
Unit
✓ from unyt import Unit
✗ from unyt.units import Unit # Redundant, exposed at top level
Used for creating custom unit objects.
G
✓ from unyt import G
Example of importing a pre-defined constant with units (Gravitational constant).
define_unit
✓ from unyt import define_unit
Function to register new units into the registry.
This quickstart demonstrates how to create unyt_array objects, perform basic arithmetic while maintaining units, and convert quantities between different unit systems. It also shows how to access pre-defined physical constants.
from unyt import unyt_array, g, cm, s, G
# Create unyt_arrays with units
mass = unyt_array([10, 20, 30], 'g')
length = unyt_array(5, cm)
time = unyt_array(2, s)
print(f"Initial mass: {mass}")
# Perform arithmetic operations
density = mass / (length**3)
print(f"Calculated density: {density}")
# Convert to different units
density_kg_m3 = density.to('kg/m**3')
print(f"Density in kg/m^3: {density_kg_m3}")
# Access constants
print(f"Gravitational constant: {G}")
Debug
Known issues
breakingunyt v3.1.0 dropped support for Python 3.9. Users on Python 3.9 must upgrade their Python version to 3.10 or newer, or stick to unyt versions older than 3.1.0.fixUpgrade Python to 3.10 or later, or pin unyt version to `<3.1.0` if 3.9 support is critical.
affects: >=3.1.0
gotchaDirect multiplication of a NumPy array by a unit symbol (e.g., `np.array([1,2,3]) * g`) was a common pattern but is discouraged or may behave unexpectedly in newer versions. The preferred method is explicit `unyt_array` creation.fixAlways initialize `unyt_array` explicitly: `unyt_array([10, 20, 30], 'g')` or `unyt_array([10, 20, 30], g)`.
affects: All versions, changed behavior in >=3.1.0
gotchaVersions of unyt prior to 3.0.4 had known incompatibilities with NumPy 2.1. While fixes have been implemented, users might encounter issues if using an older unyt with a newer NumPy.fixEnsure `unyt` is version `3.0.4` or newer when using NumPy `2.1` or later.
affects: <3.0.4
gotchaAs of unyt v3.0.2, attempting destructive edits to the default unit registry (e.g., modifying existing units or constants globally) is explicitly forbidden and will raise errors.fixIf custom unit behavior is needed, create a custom `UnitRegistry` instance and work with it locally, rather than modifying the global default registry.
affects: >=3.0.2
Errors
Common errors & fixes
unyt.exceptions.UnitConsistencyError: Cannot add quantities with incompatible dimensions
Attempting to perform an arithmetic operation (e.g., addition, subtraction) between unyt_array objects that represent physically incompatible dimensions (e.g., adding mass to length).
fixEnsure all operands in an arithmetic operation have compatible physical dimensions. If units are convertible, `unyt` will handle it, but if they are fundamentally different, this error will occur. For example, convert units before adding: `(length_in_meters + length_in_feet.to('m'))`. AttributeError: 'numpy.ndarray' object has no attribute 'to'
Trying to use `unyt_array` methods like `.to()` or `.in_units()` on a plain `numpy.ndarray` object. This typically happens when a `unyt_array` has been unintentionally converted back to a `numpy.ndarray` (e.g., via `.value` or certain operations).
fixEnsure the object is a `unyt_array` before attempting unit-aware operations. If you have the raw values, re-create a `unyt_array`: `my_unyt_array = unyt_array(my_numpy_array, 'unit')`.
TypeError: '<' not supported between instances of 'unyt_quantity' and 'float'
Attempting to compare a `unyt_quantity` or `unyt_array` directly with a bare Python `float` or `int` without explicitly converting the unyt object to a scalar value or defining the numeric value with units.
fixTo compare, either convert the `unyt_quantity` to its numerical value (`quantity.value`) or convert the bare number into a `unyt_quantity` with compatible units before comparison: `if quantity < unyt_array(10.0, quantity.units):`.
Upgrade
Version history
3.1.0latest on PyPI · released Jan 15, 2026
Audit
Dependencies
numpyrequiredCore dependency for array operations and data structures.