{"id":8753,"library":"unyt","title":"Unyt - Units for NumPy","description":"unyt is a Python package that provides NumPy arrays with units, enabling dimensional consistency checks and automatic unit conversions. It is developed as part of the yt-project and is actively maintained with a regular release cadence, typically seeing minor releases every few months and bugfix releases more frequently. The current stable version is 3.1.0.","status":"active","version":"3.1.0","language":"en","source_language":"en","source_url":"https://github.com/yt-project/unyt","tags":["units","numpy","physics","astronomy","data-analysis","scientific-computing"],"install":[{"cmd":"pip install unyt","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for array operations and data structures.","package":"numpy","optional":false}],"imports":[{"note":"Most common units and functions are exposed directly in the top-level 'unyt' namespace.","wrong":"import unyt_array # Directly importing from unyt_array submodule is not standard","symbol":"unyt_array","correct":"from unyt import unyt_array"},{"note":"Used for creating custom unit objects.","wrong":"from unyt.units import Unit # Redundant, exposed at top level","symbol":"Unit","correct":"from unyt import Unit"},{"note":"Example of importing a pre-defined constant with units (Gravitational constant).","symbol":"G","correct":"from unyt import G"},{"note":"Function to register new units into the registry.","symbol":"define_unit","correct":"from unyt import define_unit"}],"quickstart":{"code":"from unyt import unyt_array, g, cm, s, G\n\n# Create unyt_arrays with units\nmass = unyt_array([10, 20, 30], 'g')\nlength = unyt_array(5, cm)\ntime = unyt_array(2, s)\n\nprint(f\"Initial mass: {mass}\")\n\n# Perform arithmetic operations\ndensity = mass / (length**3)\nprint(f\"Calculated density: {density}\")\n\n# Convert to different units\ndensity_kg_m3 = density.to('kg/m**3')\nprint(f\"Density in kg/m^3: {density_kg_m3}\")\n\n# Access constants\nprint(f\"Gravitational constant: {G}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to 3.10 or later, or pin unyt version to `<3.1.0` if 3.9 support is critical.","message":"unyt 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.","severity":"breaking","affected_versions":">=3.1.0"},{"fix":"Always initialize `unyt_array` explicitly: `unyt_array([10, 20, 30], 'g')` or `unyt_array([10, 20, 30], g)`.","message":"Direct 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.","severity":"gotcha","affected_versions":"All versions, changed behavior in >=3.1.0"},{"fix":"Ensure `unyt` is version `3.0.4` or newer when using NumPy `2.1` or later.","message":"Versions 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.","severity":"gotcha","affected_versions":"<3.0.4"},{"fix":"If custom unit behavior is needed, create a custom `UnitRegistry` instance and work with it locally, rather than modifying the global default registry.","message":"As 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.","severity":"gotcha","affected_versions":">=3.0.2"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure 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'))`.","cause":"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).","error":"unyt.exceptions.UnitConsistencyError: Cannot add quantities with incompatible dimensions"},{"fix":"Ensure 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')`.","cause":"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).","error":"AttributeError: 'numpy.ndarray' object has no attribute 'to'"},{"fix":"To 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):`.","cause":"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.","error":"TypeError: '<' not supported between instances of 'unyt_quantity' and 'float'"}]}