{"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":"python","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,"search_vec":"'3.1.0':60 'activ':36 'analysi':67 'array':13 'astronomi':64 'automat':21 'bugfix':51 'cadenc':42 'check':19 'comput':70 'consist':18 'convers':23 'current':56 'data':66 'data-analysi':65 'develop':26 'dimension':17 'enabl':16 'everi':47 'frequent':54 'maintain':37 'minor':45 'month':49 'numpi':4,12,62 'packag':9 'part':28 'physic':63 'project':33 'provid':11 'python':8 'regular':40 'releas':41,46,52 'scientif':69 'scientific-comput':68 'see':44 'stabl':57 'typic':43 'unit':2,15,22,61 'unyt':1,5 'version':58 'yt':32 'yt-project':31","created_at":"2026-04-16T17:03:50.070476+00:00","updated_at":"2026-04-16T17:03:50.070476+00:00","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'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.1.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://unyt.readthedocs.org","github":"https://github.com/yt-project/unyt","docs":"https://unyt.readthedocs.io/en/stable/index.html","changelog":"https://unyt.readthedocs.io/en/stable/history.html","pypi":"https://pypi.org/project/unyt/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}