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. its dtype.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 Overflow
🌐
NumPy
numpy.org › devdocs › reference › typing.html
Typing (numpy.typing) — NumPy v2.6.dev0 Manual
>>> import numpy as np >>> type ImageRGB = np.ndarray[tuple[int, int, int], np.dtype[np.uint8]] >>> type Vector[S: np.generic] = np.ndarray[tuple[int], np.dtype[S]] ... A Union representing objects that can be coerced into an ndarray. ... Objects implementing the __array__ protocol. Added in version 1.20. ... Any scalar or sequence that can be interpreted as an ndarray. ... Try it in your browser! >>> import numpy as np >>> import numpy.typing as npt >>> def as_array(a: npt.ArrayLike) -> np.ndarray: ...
🌐
NumPy
numpy.org › doc › stable › reference › typing.html
Typing (numpy.typing) — NumPy v2.5 Manual
>>> import numpy as np >>> type ImageRGB = np.ndarray[tuple[int, int, int], np.dtype[np.uint8]] >>> type Vector[S: np.generic] = np.ndarray[tuple[int], np.dtype[S]] ... A Union representing objects that can be coerced into an ndarray. ... Objects implementing the __array__ protocol. New in version 1.20. ... Any scalar or sequence that can be interpreted as an ndarray. ... Try it in your browser! >>> import numpy as np >>> import numpy.typing as npt >>> def as_array(a: npt.ArrayLike) -> np.ndarray: ...
Discussions

How to type annotate mathematical operations that supports built-in numerics, collections and numpy arrays?
In scientific code that deals with mathematical operations, before type annotations, it is common to assume that any mathematical function could take in a numpy array. To be explicit you just add to your docstring that you can take array_like or ndarray (as is conventional in NumFocus project docs). More on discuss.python.org
🌐 discuss.python.org
1
1
April 2, 2022
python - Type hinting / annotation (PEP 484) for numpy.ndarray - Stack Overflow
Has anyone implemented type hinting for the specific numpy.ndarray class? Right now, I'm using typing.Any, but it would be nice to have something more specific. For instance if the NumPy people add... More on stackoverflow.com
🌐 stackoverflow.com
What's the appropriate type-hint for a function that can accept a list of floats OR a numpy array?
If your function accepts an array-like input that you intend to treat as an array, I think the "correct" thing to do is to run that input through one of the numpy.as*array() or numpy.atleast_*() functions before you use it. In both your examples, I think numpy.atleast_1d would probably be sensible. By the way, numpy does have 0-D arrays, so something like this can pass static checking and then fail at runtime if you don't run it through atleast_1d: import numpy as np import numpy.typing as npt myvar: npt.NDArray = np.array(1) print(myvar[0]) # or even print(len(myvar)) The type hints aren't enough on their own. More on reddit.com
🌐 r/learnpython
3
3
July 11, 2023
TYP: Numpy compatibility of definition of "array like"
In addition to ndarrays and scalars this category includes lists (possibly nested and with different element types) and tuples. Any argument accepted by numpy.array is array_like. Are we creating confusion by using the term ArrayLike to only mean arrays, whereas numpy defines it to include scalars? More on github.com
🌐 github.com
16
June 3, 2021
🌐
NumPy
numpy.org › doc › 2.3 › reference › typing.html
Typing (numpy.typing) — NumPy v2.3 Manual
The timedelta64 class is not considered a subclass of signedinteger, the former only inheriting from generic while static type checking. During runtime numpy aggressively casts any passed 0D arrays into their corresponding generic instance. Until the introduction of shape typing (see PEP 646) it is unfortunately not possible to make the necessary distinction between 0D and >0D arrays. While thus not strictly correct, all operations that can potentially perform a 0D-array -> scalar cast are currently annotated as exclusively returning an ndarray.
🌐
Jack Atkinson
jackatkinson.net › post › numpy_typing
Typing in numpy - Jack Atkinson's Website
April 27, 2025 - If a function that returns an NDArray returns what is realistcally a scalar, it is what numpy calls a 0D array . Your end users are unlikely to ever notice this thanks to duck typing , but internally if you know a type is guaranteed to be a scalar (0D array) and need to specify this for subsequent ...
🌐
NumPy
numpy.org › doc › 1.21 › reference › typing.html
Typing (numpy.typing) — NumPy v1.21 Manual
If it is known in advance that an operation _will_ perform a 0D-array -> scalar cast, then one can consider manually remedying the situation with either typing.cast or a # type: ignore comment. ... A Union representing objects that can be coerced into an ndarray. ... Objects implementing the __array__ protocol. ... Any scalar or sequence that can be interpreted as an ndarray. ... >>> import numpy as np >>> import numpy.typing as npt >>> def as_array(a: npt.ArrayLike) -> np.ndarray: ...
🌐
Python.org
discuss.python.org › python help
How to type annotate mathematical operations that supports built-in numerics, collections and numpy arrays? - Python Help - Discussions on Python.org
April 2, 2022 - In scientific code that deals with mathematical operations, before type annotations, it is common to assume that any mathematical function could take in a numpy array. To be explicit you just add to your docstring that you can take array_like or ndarray (as is conventional in NumFocus project docs).
Top answer
1 of 7
124

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. its dtype.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.

2 of 7
75

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.

Find elsewhere
🌐
NumPy
numpy.org › doc › 1.20 › reference › typing.html
Typing (numpy.typing) — NumPy v1.20 Manual
January 31, 2021 - The timedelta64 class is not considered a subclass of signedinteger, the former only inheriting from generic while static type checking. ... A Union representing objects that can be coerced into an ndarray. ... Objects implementing the __array__ protocol. ... Any scalar or sequence that can be interpreted as an ndarray. ... >>> import numpy as np >>> import numpy.typing as npt >>> def as_array(a: npt.ArrayLike) -> np.ndarray: ...
🌐
GitHub
github.com › pandas-dev › pandas › issues › 41807
TYP: Numpy compatibility of definition of "array like" · Issue #41807 · pandas-dev/pandas
June 3, 2021 - In pandas/_typing.py, we define ArrayLike as: ArrayLike = Union["ExtensionArray", np.ndarray] In the numpy glossary https://numpy.org/doc/stable/glossary.html?highlight=array_like, numpy defines array_like as: Any scalar or sequence that...
Author: pandas-dev
🌐
w3resource
w3resource.com › numpy › snippet › exploring-numpy-typing.php
Exploring numpy.typing for Enhanced Type Hints
ArrayLike allows the function to accept lists, tuples, or NumPy arrays. This is useful for flexible input handling. ... import numpy as np from numpy.typing import DTypeLike, NDArray # Import both DTypeLike and NDArray # Define a function that ...
🌐
NumPy
numpy.org › doc › 2.4 › reference › typing.html
Typing (numpy.typing) — NumPy v2.4 Manual
The timedelta64 class is not considered a subclass of signedinteger, the former only inheriting from generic while static type checking. During runtime numpy aggressively casts any passed 0D arrays into their corresponding generic instance. Until the introduction of shape typing (see PEP 646) it is unfortunately not possible to make the necessary distinction between 0D and >0D arrays. While thus not strictly correct, all operations that can potentially perform a 0D-array -> scalar cast are currently annotated as exclusively returning an ndarray.
🌐
Rossbar
rossbar.github.io › numpy › reference › typing.html
Typing (numpy.typing) — NumPy v1.20.dev0 Manual
Roughly speaking, typing.ArrayLike is “objects that can be used as inputs to np.array” and typing.DtypeLike is “objects that can be used as inputs to np.dtype”. NumPy is very flexible. Trying to describe the full range of possibilities statically would result in types that are not very helpful.
🌐
Medium
medium.com › @goldengrisha › using-numpy-typing-for-type-safe-list-handling-in-python-35f8c99c76ac
Using numpy.typing for Type-Safe List Handling in Python | by Gregory Kovalchuk | Medium
February 19, 2025 - The key types we’ll focus on are: NDArray: Represents a NumPy array with a specific dtype. ArrayLike: Represents anything convertible to a NumPy array (e.g., lists, tuples, or existing arrays).
🌐
GitHub
github.com › numpy › numpy › issues › 23745
ENH: Update numpy.typing.ArrayLike to allow specification of both dtype and shape/ndim · Issue #23745 · numpy/numpy
May 10, 2023 - Please update ArrayLike to include a strict shape or range of shapes, or ndim, but not both. Rationale: I would like to be able to specify that custom type annotation RGBImage should be something akin to TRGBImage=numpy.typing.NDArray[dtype=np.uint8, ndim=3] By similar reasoning, the following use cases would also be relevant ·
Author: numpy
🌐
GitHub
github.com › python › typing › discussions › 1206
numpy errors · python/typing · Discussion #1206
June 6, 2022 - This explains a lot. npt.ArrayLike is a union of all types that can safely(-ish) be converted into an np.ndarray, including things like scalars and nested lists; it does not represent some type of duck-array.
Author: python
🌐
NumPy
numpy.org › doc › 2.2 › reference › typing.html
Typing (numpy.typing) — NumPy v2.2 Manual
The timedelta64 class is not considered a subclass of signedinteger, the former only inheriting from generic while static type checking. During runtime numpy aggressively casts any passed 0D arrays into their corresponding generic instance. Until the introduction of shape typing (see PEP 646) it is unfortunately not possible to make the necessary distinction between 0D and >0D arrays. While thus not strictly correct, all operations are that can potentially perform a 0D-array -> scalar cast are currently annotated as exclusively returning an ndarray.
🌐
Velog
velog.io › @jk01019 › numpy-type-annotation
numpy type annotation
February 24, 2023 - from numpy.typing import ArrayLike def compute_mean(x: ArrayLike) -> float: x_arr = np.array(x) # convert to a NumPy array return np.mean(x_arr) type을 구체화할 수 있는데(해야 하는데), 안하려는 목적으로 쓰면 안됨 · import numpy as np def some_function(x: np.ndarray, y: np.ndarray) -> np.ndarray: return x + y
🌐
Runebook.dev
runebook.dev › en › docs › numpy › reference › typing › numpy.typing.NDArray
Beyond NDArray: A Look at numpy.typing.ArrayLike
Sometimes, NDArray might be too strict for your needs. This is where ArrayLike comes in handy. ArrayLike is a type hint that represents anything that can be converted into a NumPy array, such as lists, tuples, or scalars.
🌐
Lightrun
lightrun.com › answers › beartype-beartype-cannot-use-numpytypingndarray-type-hints
Cannot use numpy.typing.NDArray type hints
$ ipython3.8 >>> import numpy as np >>> import numpy.typing as npt >>> hint = npt.NDArray[np.float64] >>> repr(hint).startswith('numpy.ndarray[') True $ ipython3.9 >>> import numpy as np >>> import numpy.typing as npt >>> hint = npt.NDArray[np.float64] >>> repr(hint).startswith('numpy.ndarray[') True · I horrify even myself. 🙀 ... It is so nice to see the impressive pace at which beartype is developing! ... Now that NDArray is supported by the latest release, one could add the support of ArrayLike to the roadmap.