{"id":2390,"library":"array-api-compat","title":"Array API compatibility library for Python","description":"array-api-compat is a small wrapper around popular array libraries like NumPy, CuPy, PyTorch, Dask, JAX, ndonnx, and Sparse. Its primary goal is to make these libraries compatible with the Python Array API standard, allowing array-consuming libraries to write array-agnostic code today, even if the underlying array libraries do not yet fully implement the standard. The library is actively maintained by the Consortium for Python Data API Standards. The current version is 1.14.0, with ongoing development.","status":"active","version":"1.14.0","language":"en","source_language":"en","source_url":"https://github.com/data-apis/array-api-compat","tags":["array-api","numpy","pytorch","cupy","dask","jax","data-apis","interoperability","numerical-computing"],"install":[{"cmd":"pip install array-api-compat","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false},{"reason":"Provides Array API compatible namespace for NumPy arrays. Automatically imported if a NumPy array is passed to array_namespace.","package":"numpy","optional":true},{"reason":"Provides Array API compatible namespace for CuPy arrays. Automatically imported if a CuPy array is passed to array_namespace.","package":"cupy","optional":true},{"reason":"Provides Array API compatible namespace for PyTorch tensors. Automatically imported if a PyTorch tensor is passed to array_namespace.","package":"torch","optional":true},{"reason":"Provides Array API compatible namespace for Dask arrays. Automatically imported if a Dask array is passed to array_namespace.","package":"dask","optional":true},{"reason":"Supports JAX arrays via helper functions; JAX itself implements Array API support in jax.numpy (v0.4.32+).","package":"jax","optional":true},{"reason":"Supports PyData/Sparse arrays via helper functions; Sparse itself implements Array API support.","package":"sparse","optional":true},{"reason":"Supports ndonnx arrays via helper functions; ndonnx itself implements Array API support.","package":"ndonnx","optional":true}],"imports":[{"note":"The primary entry point to get an Array API compliant namespace from input arrays.","symbol":"array_namespace","correct":"from array_api_compat import array_namespace"},{"note":"Directly imports the Array API compatible wrapper for NumPy. The native NumPy namespace (especially pre-2.0) may not be fully compliant with the Array API standard.","wrong":"import numpy as xp","symbol":"numpy_namespace","correct":"import array_api_compat.numpy as xp"},{"note":"Directly imports the Array API compatible wrapper for PyTorch. The native PyTorch namespace may not be fully compliant with the Array API standard.","wrong":"import torch as xp","symbol":"torch_namespace","correct":"import array_api_compat.torch as xp"}],"quickstart":{"code":"import numpy as np\nfrom array_api_compat import array_namespace\n\ndef process_arrays(x, y):\n    xp = array_namespace(x, y)\n    # Now use xp as the array API compliant namespace\n    result = xp.mean(x, axis=0) + 2 * xp.std(y, axis=0)\n    return result\n\n# Example usage with NumPy arrays\na = np.array([1.0, 2.0, 3.0])\nb = np.array([4.0, 5.0, 6.0])\n\noutput = process_arrays(a, b)\nprint(output)\n# Expected output type is the same as input (e.g., numpy.ndarray)\nprint(type(output))","lang":"python","description":"This quickstart demonstrates the recommended usage of `array-api-compat` by obtaining an Array API compliant namespace using `array_namespace()`. This namespace (`xp`) can then be used with any supported array type (like NumPy, PyTorch, CuPy, etc.), enabling generic array-agnostic code."},"warnings":[{"fix":"Upgrade to Python 3.9 or newer.","message":"Support for Python 3.8 was dropped in version 1.15.0.dev0 (March 29, 2024). Users on Python 3.8 will need to upgrade their Python version to use recent `array-api-compat` releases.","severity":"breaking","affected_versions":">=1.15.0.dev0"},{"fix":"Rely on functions from the `xp` (array_api_compat) namespace rather than direct array object methods/operators for Array API compliant behavior. Use helper functions like `array_api_compat.size()` where native library methods are incompatible (e.g., `torch.Tensor.size`).","message":"`array-api-compat` is a wrapper and does not monkey-patch or modify the underlying array objects. This means array object *methods* or *operators* that behave differently from the Array API standard might remain non-compliant. Users should prefer elementwise functions (e.g., `xp.add(x, y)` instead of `x + y`) and provided helper functions (e.g., `array_api_compat.size(x)` instead of `x.size` for PyTorch) for consistent behavior.","severity":"gotcha","affected_versions":"all"},{"fix":"Consult the `array-api-compat` changelog and test thoroughly when upgrading NumPy 2.x or `array-api-compat` versions to ensure expected behavior.","message":"The behavior of `array_api_compat` with NumPy 2.0 has changed. Initially, NumPy 2.0 was unwrapped due to its inherent Array API support, but later versions of `array-api-compat` re-wrapped it for 2023.12 standard compatibility. This could lead to subtle behavioral differences or regressions depending on the specific versions of `array-api-compat` and NumPy in use.","severity":"gotcha","affected_versions":">=1.15.0.dev0"},{"fix":"Be aware that the `xp` namespace will only contain functions specified by the Array API standard. For non-standard functions, you may need to use library-specific imports or `array-api-extra`.","message":"`array-api-compat` explicitly avoids implementing functions that are not part of the Array API standard. This design choice keeps the library minimal and prevents it from inadvertently becoming a de facto standard. Consequently, if a function is commonly available in a specific array library but not in the Array API standard, it will not be exposed via `array-api-compat`.","severity":"gotcha","affected_versions":"all"},{"fix":"Exercise caution when using sorting, linear algebra, or FFT operations with Dask arrays via `array-api-compat`. Verify behavior against Dask's native implementation if unexpected results occur.","message":"Dask support within `array-api-compat` has known limitations. Specifically, `sort`, `argsort`, and full support for the `linalg` and `fft` extensions may be missing or non-compliant with the Array API standard. Functions within `dask.array.fft` are typically the original, unwrapped Dask functions.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}