There is a numpy.typing module with an NDArray generic type.
From the Numpy 2.3 docs:
numpy.typing.NDArray = numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[~_ScalarT]]A
np.ndarray[tuple[Any, ...], np.dtype[ScalarT]]type alias generic w.r.t. itsdtype.type.Can be used during runtime for typing arrays with a given dtype and unspecified shape.
Examples:
>>> import numpy as np >>> import numpy.typing as npt >>> print(npt.NDArray) numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[~_ScalarT]] >>> print(npt.NDArray[np.float64]) numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[numpy.float64]] >>> NDArrayInt = npt.NDArray[np.int_] >>> a: NDArrayInt = np.arange(10) >>> def func(a: npt.ArrayLike) -> npt.NDArray[Any]: ... return np.array(a)
As of 2025-07-17, support for shapes is still a work in progress per numpy/numpy#16544.
Answer from Jasha on Stack OverflowHow to type annotate mathematical operations that supports built-in numerics, collections and numpy arrays?
python - Type hinting / annotation (PEP 484) for numpy.ndarray - Stack Overflow
What's the appropriate type-hint for a function that can accept a list of floats OR a numpy array?
TYP: Numpy compatibility of definition of "array like"
There is a numpy.typing module with an NDArray generic type.
From the Numpy 2.3 docs:
numpy.typing.NDArray = numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[~_ScalarT]]A
np.ndarray[tuple[Any, ...], np.dtype[ScalarT]]type alias generic w.r.t. itsdtype.type.Can be used during runtime for typing arrays with a given dtype and unspecified shape.
Examples:
>>> import numpy as np >>> import numpy.typing as npt >>> print(npt.NDArray) numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[~_ScalarT]] >>> print(npt.NDArray[np.float64]) numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[numpy.float64]] >>> NDArrayInt = npt.NDArray[np.int_] >>> a: NDArrayInt = np.arange(10) >>> def func(a: npt.ArrayLike) -> npt.NDArray[Any]: ... return np.array(a)
As of 2025-07-17, support for shapes is still a work in progress per numpy/numpy#16544.
Update
Check recent numpy versions for a new typing module
https://numpy.org/doc/stable/reference/typing.html#module-numpy.typing
dated answer
It looks like typing module was developed at:
https://github.com/python/typing
The main numpy repository is at
https://github.com/numpy/numpy
Python bugs and commits can be tracked at
http://bugs.python.org/
The usual way of adding a feature is to fork the main repository, develop the feature till it is bomb proof, and then submit a pull request. Obviously at various points in the process you want feedback from other developers. If you can't do the development yourself, then you have to convince someone else that it is a worthwhile project.
cython has a form of annotations, which it uses to generate efficient C code.
You referenced the array-like paragraph in numpy documentation. Note its typing information:
A simple way to find out if the object can be converted to a numpy array using array() is simply to try it interactively and see if it works! (The Python Way).
In other words the numpy developers refuse to be pinned down. They don't, or can't, describe in words what kinds of objects can or cannot be converted to np.ndarray.
In [586]: np.array({'test':1}) # a dictionary
Out[586]: array({'test': 1}, dtype=object)
In [587]: np.array(['one','two']) # a list
Out[587]:
array(['one', 'two'],
dtype='<U3')
In [589]: np.array({'one','two'}) # a set
Out[589]: array({'one', 'two'}, dtype=object)
For your own functions, an annotation like
def foo(x: np.ndarray) -> np.ndarray:
works. Of course if your function ends up calling some numpy function that passes its argument through asanyarray (as many do), such an annotation would be incomplete, since your input could be a list, or np.matrix, etc.
When evaluating this question and answer, pay attention to the date. 484 was a relatively new PEP back then, and code to make use of it for standard Python still in development. But it looks like the links provided are still valid.
This is what I've got so far
import numpy.typing as npt
def myfunc(mylist : list[float] | npt.NDArray):
print(len(mylist))It works, but I wonder if there's another way to do this that doesn't involve the |?
I tried npt.ArrayLike, but it complains when you try to access an element from an ArrayLike object, i.e. the following program results in an error:
import numpy as np import numpy.typing as npt myvar: npt.ArrayLike = np.array([1,2,3]) # this line is fine print(myvar[0]) # this line throws an error with mypy because apparently ArrayLike is not indexable