Quick Start#

PyUnitWizard 0.26.0 and later support Linux and macOS Apple Silicon (arm64) with Python 3.11–3.14. Intel macOS is outside the supported matrix; concrete user demand may reopen the suite decision. Earlier releases were validated only through Python 3.13. Windows support remains outside the maintained platform matrix.

This walkthrough is intentionally short. Its purpose is to let you verify, in a few minutes, whether PyUnitWizard matches your workflow expectations.

We will configure a single backend, construct one quantity, convert it, and validate that compatibility and dimensional checks behave as expected.

Start by installing the package:

conda install -c uibcdf 'pyunitwizard>=0.26.0'

The public PyPI index does not currently distribute PyUnitWizard or its required SMonitor and DepDigest versions. If you need a source installation, install those dependencies from Conda first; follow the installation guide.

Now configure runtime behavior explicitly:

import pyunitwizard as puw

puw.configure.reset()
puw.configure.load_library(["pint"])
puw.configure.set_default_form("pint")
puw.configure.set_default_parser("pint")

At this point, parsing and output form are deterministic, which is the first requirement for reproducible library behavior and stable tests.

Create and convert a quantity:

distance = puw.quantity(1.0, "nanometer")
distance_angstrom = puw.convert(distance, to_unit="angstrom")
print(puw.to_string(distance_angstrom))

You should obtain a value equivalent to 10.0 angstrom.

If another library created a quantity with its own Pint UnitRegistry, bring it into PyUnitWizard’s registry before combining it with PyUnitWizard values:

import pint

foreign = pint.UnitRegistry().Quantity(3.0, "nanometer")
local = puw.convert(foreign, to_form="pint")
total = distance + local

puw.is_quantity(foreign) recognizes it. Conversion checks that the source and target unit definitions have matching dimensions, base units, scale and offset (within 1e-12 relative tolerance), and raises ValueError if they differ.

Array quantities can also pass through the text form:

import numpy as np

coordinates = puw.quantity(np.array([1.5, 2.25]), "angstrom")
text = puw.convert(coordinates, to_form="string")
restored = puw.quantity(text)

The text contains comma-separated lists that preserve numeric values and array shape when parsed again. Use the verified record form when the original NumPy dtype must also survive serialization.

Finally, verify compatibility and dimensional assumptions:

a = puw.quantity(1.0, "nanometer")
b = puw.quantity(10.0, "angstrom")

print(puw.are_compatible(a, b))
print(puw.check(a, dimensionality={"[L]": 1}))
print(puw.has_unit(a, "nm"))

All three checks should return True. has_unit is the inexpensive choice when you need exact unit identity rather than dimensional compatibility.

If you prefer notebook examples for this same flow, open:

If this behavior is what you need, continue with Mini Library Walkthrough.