Install & Compatibility
Where this runs
tested against v20260602.2.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.052s · 89.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 0.046s · 86MB
89MB installed
● package 89MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CanArray
✓ from numpy_typing_compat import CanArray
A primary type alias for `np.ndarray`, offering subscriptability (`CanArray[DType]`) for compatibility with older NumPy versions where such typing might be missing or incorrect.
DTypeLike
✓ from numpy_typing_compat import DTypeLike
Type alias representing various ways to specify a NumPy dtype.
ArrayLike
✓ from numpy_typing_compat import ArrayLike
Type alias representing objects that can be converted to a NumPy array.
int_
✓ from numpy_typing_compat import int_
Compatibility alias for NumPy's integer type, useful for older NumPy versions.
This quickstart demonstrates how to use `CanArray` and `DTypeLike` for type hinting NumPy arrays. The library primarily provides these compatibility types for static analysis on projects using older NumPy versions, where native type hints might be less mature.
import numpy as np
from numpy_typing_compat import CanArray, DTypeLike
def process_numeric_array(data: CanArray[DTypeLike]) -> CanArray[DTypeLike]:
"""
Processes a NumPy array, using CanArray for type hinting
compatibility, especially with older NumPy versions where
type stubs might be less complete.
"""
print(f"Input array type: {type(data)}, dtype: {data.dtype}")
# Perform some array operation
return data * 2
if __name__ == "__main__":
# Example with a float array
my_float_array = np.array([1.0, 2.5, 3.0], dtype=np.float64)
result_float_array = process_numeric_array(my_float_array)
print(f"Result float array: {result_float_array}, dtype: {result_float_array.dtype}\n")
# Example with an integer array
my_int_array = np.array([10, 20, 30], dtype=np.int32)
result_int_array = process_numeric_array(my_int_array)
print(f"Result int array: {result_int_array}, dtype: {result_int_array.dtype}")
Debug
Known issues
gotchaThe `CanArray` type's subscriptability (e.g., `CanArray[np.float64]`) and its direct aliasing behavior for `np.ndarray` were improved and fixed in `v20250729` and `v20250730`. Earlier versions of `numpy-typing-compat` might exhibit unexpected behavior or errors when using `CanArray` with older NumPy versions (specifically `<2.1`).fixEnsure you are using `numpy-typing-compat` version `v20250730` or newer for consistent `CanArray` behavior, especially when targeting NumPy versions older than 2.1.
affects: <v20250730
gotchaThis library is designed as a *compatibility layer* for *older* NumPy versions to improve static typing. If you are using recent versions of NumPy (e.g., NumPy 2.x), many of these types might already be natively available or handled differently. Relying solely on `numpy-typing-compat` without checking NumPy's native typing capabilities for your specific version might introduce unnecessary abstractions or mask issues.fixUnderstand that `numpy-typing-compat` fills gaps in older NumPy's typing. For newer NumPy versions, consult NumPy's official typing documentation first.
affects: All versions
breakingPrior to `v20250818`, users running `numpy-typing-compat` on Python versions older than 3.10 could encounter `ImportError` runtime errors. The library now officially requires Python 3.11 or newer.fixUpgrade to `numpy-typing-compat` `v20250818` or newer, and ensure your Python environment is `3.11` or above.
affects: <v20250818` when used with Python `<3.10`. (Note: current version requires `Python >=3.11`.)
gotchaCertain types like `long`, `ulong`, `StringDType`, and `array_api` were added to the `numpy_typing_compat` namespace in `v20250725`. If your codebase relies on these specific aliases for older NumPy compatibility, ensure you're on a sufficiently recent version.fixUpdate `numpy-typing-compat` to `v20250725` or newer to access these specific typing aliases.
affects: <v20250725
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'numpy_typing_compat'
The numpy-typing-compat package is not installed in your current Python environment or is not accessible on the Python path.
fixRun `pip install numpy-typing-compat` to install the package.
AttributeError: module 'numpy' has no attribute 'long'
This error occurs when trying to use `np.long` (or `np.ulong`) in code with a NumPy version older than 2.0. The `long` and `ulong` scalar types were introduced in NumPy 2.0, so they are not available in earlier versions.
fixImport `long` (or `ulong`) from `numpy_typing_compat` instead: `from numpy_typing_compat import long`. This provides a compatible alias for older NumPy versions.
Type checking error: 'ABCPolyBase' is not subscriptable
This Mypy or Pyright error can occur when trying to use `numpy.polynomial._polybase.ABCPolyBase` with inconsistent type parameter usage across different NumPy versions. `ABCPolyBase` became a generic type in NumPy 2.1, and its type parameter became optional in NumPy 2.2, leading to potential type-checking conflicts if not handled.
fixUse `from numpy_typing_compat import ABCPolyBase`. This alias provides consistent type hint behavior for `ABCPolyBase` across various NumPy versions.
Type checking error: 'bool' is not a generic class
This error (from Mypy or Pyright) can arise when attempting to use `np.bool[Literal[True]]` or `np.bool[Literal[False]]` for type hinting on NumPy versions older than 2.2. In NumPy 2.2, `np.bool` became a generic type accepting type parameters `True` or `False`.
fixImport and use `LiteralTrue` or `LiteralFalse` from `numpy_typing_compat` instead: `from numpy_typing_compat import LiteralTrue, LiteralFalse`. These types provide compatibility for boolean type hints across NumPy versions, handling the generic `np.bool` in newer versions and `Literal` types in older ones.
Upgrade
Version history
20260602.2.5latest on PyPI · released Jun 2, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.11 or newer.
numpyrequiredThis library provides typing stubs and compatibility types for NumPy. While not a direct runtime dependency, it is useless without NumPy installed.