{"id":780,"library":"ml-dtypes","title":"ML-Dtypes","description":"ml_dtypes is a stand-alone implementation of several NumPy dtype extensions used in machine learning libraries. These include bfloat16, various 8-bit, 6-bit, 4-bit floating point representations, and narrow integer types (int1, int2, int4, uint1, uint2, uint4). It is currently at version 0.5.4 and receives regular updates, primarily driven by its use in projects like JAX.","status":"active","version":"0.5.4","language":"python","source_language":"en","source_url":"https://github.com/jax-ml/ml_dtypes","tags":["numpy","machine-learning","dtypes","bfloat16","float8","low-precision-inference","jax"],"install":[{"cmd":"pip install ml-dtypes","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Core dependency for dtype extensions.","package":"numpy","optional":false},{"reason":"Used in testing, optional for core library use.","package":"absl-py","optional":true},{"reason":"Used in testing, optional for core library use.","package":"pytest","optional":true},{"reason":"Used in testing, optional for core library use.","package":"pytest-xdist","optional":true}],"imports":[{"note":"Commonly imported directly for specific dtypes.","symbol":"bfloat16","correct":"from ml_dtypes import bfloat16"},{"note":"Importing the module registers its data types with NumPy, allowing them to be referred to by string names like 'bfloat16' or 'float8_e5m2'.","symbol":"ml_dtypes module (for registration)","correct":"import ml_dtypes\nimport numpy as np\nnp.dtype('bfloat16')"}],"quickstart":{"code":"import numpy as np\nfrom ml_dtypes import bfloat16, float8_e5m2\n\n# Create an array with bfloat16 dtype\nb_array = np.zeros(4, dtype=bfloat16)\nprint(f\"bfloat16 array: {b_array}, dtype: {b_array.dtype}\")\n\n# Create an array using a string name (after ml_dtypes import registers it)\nf8_array = np.array([0.5, 1.0, 1.5, 2.0], dtype='float8_e5m2')\nprint(f\"float8_e5m2 array: {f8_array}, dtype: {f8_array.dtype}\")\n\n# Perform a basic operation\nsum_f8 = np.sum(f8_array)\nprint(f\"Sum of float8_e5m2 array: {sum_f8}, dtype: {type(sum_f8)}\")","lang":"python","description":"This example demonstrates importing specific dtypes and creating NumPy arrays with them. It also shows how the types are registered with NumPy, allowing creation via string names. Note that basic NumPy operations are supported."},"warnings":[{"fix":"Regenerate any pickled `ml_dtypes` values using the current version of the library.","message":"Values pickled with previous versions of `ml_dtypes` (prior to 0.5.4, due to `NPY_NEEDS_PYAPI` removal from dtype flags) are incompatible with the current release. These values must be regenerated with `ml_dtypes>=0.5.4`.","severity":"breaking","affected_versions":"<0.5.4"},{"fix":"Update dependent libraries (e.g., JAX, TensorFlow) to versions compatible with `ml_dtypes` >= 0.3.0, or pin `ml_dtypes` to 0.2.0 if an older dependency is strictly required.","message":"The `float8_e4m3b11` dtype was deprecated starting from version 0.3.0. This change caused `AttributeError` issues in older versions of dependent libraries like JAX and TensorFlow that expected its presence.","severity":"deprecated","affected_versions":">=0.3.0"},{"fix":"Be aware of the unpacked representation for narrow integer types, especially when memory efficiency is critical. The lower bits store the value, while the upper bits are ignored.","message":"The narrow integer types (e.g., `int2`, `int4`, `uint2`, `uint4`) are implemented as 'unpacked' representations. Each element is padded up to a byte in memory because NumPy does not natively support types smaller than a single byte. This means these types may consume more memory than their bit-width suggests if memory layout is not carefully considered.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Prefer direct imports (e.g., `from ml_dtypes import bfloat16`) over string-based `np.dtype` creation where possible, to future-proof your code against potential deprecations.","message":"There is an open proposal to deprecate the creation of `ml_dtypes` dtypes via string names using `np.dtype('typename')` in a future release, potentially in favor of direct imports. While currently supported, users should be aware of this potential future change.","severity":"gotcha","affected_versions":"Future (discussion in progress)"},{"fix":"Ensure a C++ compiler (such as g++ or clang++) is installed in the build environment. For Alpine Linux, this can be resolved by installing the `build-base` or `g++` package.","message":"Building `ml-dtypes` requires a C++ compiler (e.g., g++) for its C++ extensions. The installation will fail with 'command 'g++' failed: No such file or directory' if a suitable compiler is not present in the environment.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.5.4':50 '4':30 '6':28 '8':26 'alon':10 'bfloat16':24,69 'bit':27,29,31 'current':47 'driven':56 'dtype':3,5,15,68 'extens':16 'float':32 'float8':70 'implement':11 'includ':23 'infer':74 'int1':39 'int2':40 'int4':41 'integ':37 'jax':63,75 'learn':20,67 'librari':21 'like':62 'low':72 'low-precision-infer':71 'machin':19,66 'machine-learn':65 'ml':2,4 'ml-dtype':1 'narrow':36 'numpi':14,64 'point':33 'precis':73 'primarili':55 'project':61 'receiv':52 'regular':53 'represent':34 'sever':13 'stand':9 'stand-alon':8 'type':38 'uint1':42 'uint2':43 'uint4':44 'updat':54 'use':17,59 'various':25 'version':49","created_at":"2026-03-29T04:21:22.573501+00:00","updated_at":"2026-04-16T16:36:34.000297+00:00","problems":[{"fix":"Ensure `ml-dtypes` and its dependencies (like JAX and NumPy) are compatible versions. Upgrade `ml-dtypes` to the latest version (`pip install --upgrade ml-dtypes`) or downgrade to a version known to be compatible with your other libraries. Refer to the documentation or release notes for exact dtype availability.","cause":"This error typically occurs when a specific dtype, like 'float8_e4m3b11' (or 'int2', 'float4_e2m1fn', etc.), is accessed from the `ml_dtypes` module but is either missing, renamed, or not available in the installed version of the library, often due to a version mismatch with consuming libraries like JAX or TensorFlow.","error":"AttributeError: module 'ml_dtypes' has no attribute 'float8_e4m3b11'"},{"fix":"Upgrade NumPy to a more recent version (e.g., NumPy 2.x or later) that offers improved compatibility with `ml_dtypes`' custom float types. Run `pip install --upgrade numpy`.","cause":"This error arises when NumPy's `isnan` ufunc is called with `ml_dtypes` types (e.g., `float8_e8m0fnu`), indicating an incompatibility, typically with older versions of NumPy that do not fully support these custom data types.","error":"TypeError: ufunc 'isnan' not supported for the input types"},{"fix":"Manage your Python environment carefully using virtual environments. Explicitly pin compatible versions of `ml-dtypes`, `numpy`, JAX, and TensorFlow based on their official documentation to avoid conflicts. For example: `pip install ml-dtypes==0.5.4 numpy==1.26.4 jax==0.4.23`.","cause":"This informational message, often preceding a build failure, indicates that `pip` is struggling to resolve conflicting dependency requirements for `ml-dtypes` among various installed or requested packages (e.g., TensorFlow, JAX, and NumPy), leading to an inability to find a compatible set of versions.","error":"INFO: pip is looking at multiple versions of ml-dtypes to determine which version"},{"fix":"Check for updates to the consuming library (e.g., `mlx.core`) or `ml-dtypes` itself, as this is likely a bug fix that will be addressed in a new release. If a fix isn't available, consider explicit type casting in your code if the consuming library provides such an option, or report the issue to the respective library's maintainers.","cause":"This is a reported bug where a consuming library (e.g., `mlx.core`) incorrectly interprets `ml_dtypes.bfloat16` NumPy arrays as `complex64` instead of the intended bfloat16 type.","error":"np.ndarray of bfloat16 using ml_dtypes is being interpreted as complex64"}],"ecosystem":"pypi","meta_description":null,"install_score":43,"quickstart_score":30,"quickstart_tag":"draft","pypi_latest":"0.6.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/jax-ml/ml_dtypes","docs":null,"changelog":null,"pypi":"https://pypi.org/project/ml-dtypes/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"draft"}}