Data type API#
The standard array can have 25 different data types (and has some support for adding your own types). These data types all have an enumerated type, an enumerated typecharacter, and a corresponding array scalar Python type object (placed in a hierarchy). There are also standard C typedefs to make it easier to manipulate elements of the given data type. For the numeric types, there are also bitwidth equivalent C typedefs and named typenumbers that make it easier to select the precision desired.
Warning
The names for the types in c code follows c naming conventions
more closely. The Python names for these types follow Python
conventions. Thus, NPY_FLOAT
picks up a 32bit float in
C, but numpy.float64
in Python corresponds to a 64bit
double. The bitwidth names can be used in both Python and C for
clarity.
Enumerated types#

enum NPY_TYPES#
There is a list of enumerated types defined providing the basic 25 data types plus some useful generic names. Whenever the code requires a type number, one of these enumerated types is requested. The types are all called
NPY_{NAME}
:
enumerator NPY_BOOL#
The enumeration value for the boolean type, stored as one byte. It may only be set to the values 0 and 1.

enumerator NPY_BYTE#

enumerator NPY_INT8#
The enumeration value for an 8bit/1byte signed integer.

enumerator NPY_SHORT#

enumerator NPY_INT16#
The enumeration value for a 16bit/2byte signed integer.

enumerator NPY_INT#

enumerator NPY_INT32#
The enumeration value for a 32bit/4byte signed integer.

enumerator NPY_LONG#
Equivalent to either NPY_INT or NPY_LONGLONG, depending on the platform.

enumerator NPY_LONGLONG#

enumerator NPY_INT64#
The enumeration value for a 64bit/8byte signed integer.

enumerator NPY_UBYTE#

enumerator NPY_UINT8#
The enumeration value for an 8bit/1byte unsigned integer.

enumerator NPY_USHORT#

enumerator NPY_UINT16#
The enumeration value for a 16bit/2byte unsigned integer.

enumerator NPY_UINT#

enumerator NPY_UINT32#
The enumeration value for a 32bit/4byte unsigned integer.

enumerator NPY_ULONG#
Equivalent to either NPY_UINT or NPY_ULONGLONG, depending on the platform.

enumerator NPY_ULONGLONG#

enumerator NPY_UINT64#
The enumeration value for a 64bit/8byte unsigned integer.

enumerator NPY_HALF#

enumerator NPY_FLOAT16#
The enumeration value for a 16bit/2byte IEEE 7542008 compatible floating point type.

enumerator NPY_FLOAT#

enumerator NPY_FLOAT32#
The enumeration value for a 32bit/4byte IEEE 754 compatible floating point type.

enumerator NPY_DOUBLE#

enumerator NPY_FLOAT64#
The enumeration value for a 64bit/8byte IEEE 754 compatible floating point type.

enumerator NPY_LONGDOUBLE#
The enumeration value for a platformspecific floating point type which is at least as large as NPY_DOUBLE, but larger on many platforms.

enumerator NPY_CFLOAT#

enumerator NPY_COMPLEX64#
The enumeration value for a 64bit/8byte complex type made up of two NPY_FLOAT values.

enumerator NPY_CDOUBLE#

enumerator NPY_COMPLEX128#
The enumeration value for a 128bit/16byte complex type made up of two NPY_DOUBLE values.

enumerator NPY_CLONGDOUBLE#
The enumeration value for a platformspecific complex floating point type which is made up of two NPY_LONGDOUBLE values.

enumerator NPY_DATETIME#
The enumeration value for a data type which holds dates or datetimes with a precision based on selectable date or time units.

enumerator NPY_TIMEDELTA#
The enumeration value for a data type which holds lengths of times in integers of selectable date or time units.

enumerator NPY_STRING#
The enumeration value for nullpadded byte strings of a selectable size. The strings have a fixed maximum size within a given array.

enumerator NPY_UNICODE#
The enumeration value for UCS4 strings of a selectable size. The strings have a fixed maximum size within a given array.

enumerator NPY_VSTRING#
The enumeration value for UTF8 variablewidth strings. Note that this dtype holds an array of references, with string data stored outside of the array buffer. Use the C API for working with numpy variablewidth static strings to access the string data in each array entry.
Note
This DType is newstyle and is not included in
NPY_NTYPES_LEGACY
.

enumerator NPY_OBJECT#
The enumeration value for references to arbitrary Python objects.

enumerator NPY_VOID#
Primarily used to hold struct dtypes, but can contain arbitrary binary data.
Some useful aliases of the above types are

enumerator NPY_INTP#
The enumeration value for a signed integer of type
Py_ssize_t
(same asssize_t
if defined). This is the type used by all arrays of indices.Changed in version 2.0: Previously, this was the same as
intptr_t
(same size as a pointer). In practice, this is identical except on very niche platforms. You can use the'p'
character code for the pointer meaning.

enumerator NPY_UINTP#
The enumeration value for an unsigned integer type that is identical to a
size_t
.Changed in version 2.0: Previously, this was the same as
uintptr_t
(same size as a pointer). In practice, this is identical except on very niche platforms. You can use the'P'
character code for the pointer meaning.

enumerator NPY_MASK#
The enumeration value of the type used for masks, such as with the
NPY_ITER_ARRAYMASK
iterator flag. This is equivalent toNPY_UINT8
.

enumerator NPY_DEFAULT_TYPE#
The default type to use when no dtype is explicitly specified, for example when calling np.zero(shape). This is equivalent to
NPY_DOUBLE
.

enumerator NPY_BOOL#
Other useful related constants are

NPY_NTYPES_LEGACY#
The number of builtin NumPy types written using the legacy DType system. New NumPy dtypes will be written using the new DType API and may not function in the same manner as legacy DTypes. Use this macro if you want to handle legacy DTypes using different code paths or if you do not want to update code that uses
NPY_NTYPES_LEGACY
and does not work correctly with new DTypes.Note
Newly added DTypes such as
NPY_VSTRING
will not be counted inNPY_NTYPES_LEGACY
.

NPY_NOTYPE#
A signal value guaranteed not to be a valid type enumeration number.

NPY_USERDEF#
The start of type numbers used for legacy Custom Data types. Newstyle user DTypes currently are currently not assigned a typenumber.
Note
The total number of user dtypes is limited to below
NPY_VSTRING
. Higher numbers are reserved to future newstyle DType use.
The various character codes indicating certain types are also part of
an enumerated list. References to type characters (should they be
needed at all) should always use these enumerations. The form of them
is NPY_{NAME}LTR
where {NAME}
can be
BOOL, BYTE, UBYTE, SHORT, USHORT, INT, UINT, LONG, ULONG, LONGLONG, ULONGLONG, HALF, FLOAT, DOUBLE, LONGDOUBLE, CFLOAT, CDOUBLE, CLONGDOUBLE, DATETIME, TIMEDELTA, OBJECT, STRING, UNICODE, VSTRING, VOID
INTP, UINTP
GENBOOL, SIGNED, UNSIGNED, FLOATING, COMPLEX
The latter group of {NAME}s
corresponds to letters used in the array
interface typestring specification.
Defines#
Max and min values for integers#
NPY_MAX_INT{bits}
,NPY_MAX_UINT{bits}
,NPY_MIN_INT{bits}
These are defined for
{bits}
= 8, 16, 32, 64, 128, and 256 and provide the maximum (minimum) value of the corresponding (unsigned) integer type. Note: the actual integer type may not be available on all platforms (i.e. 128bit and 256bit integers are rare).NPY_MIN_{type}
This is defined for
{type}
= BYTE, SHORT, INT, LONG, LONGLONG, INTPNPY_MAX_{type}
This is defined for all defined for
{type}
= BYTE, UBYTE, SHORT, USHORT, INT, UINT, LONG, ULONG, LONGLONG, ULONGLONG, INTP, UINTP
Number of bits in data types#
All NPY_SIZEOF_{CTYPE}
constants have corresponding
NPY_BITSOF_{CTYPE}
constants defined. The NPY_BITSOF_{CTYPE}
constants provide the number of bits in the data type. Specifically,
the available {CTYPE}s
are
BOOL, CHAR, SHORT, INT, LONG, LONGLONG, FLOAT, DOUBLE, LONGDOUBLE
Bitwidth references to enumerated typenums#
All of the numeric data types (integer, floating point, and complex)
have constants that are defined to be a specific enumerated type
number. Exactly which enumerated type a bitwidth type refers to is
platform dependent. In particular, the constants available are
PyArray_{NAME}{BITS}
where {NAME}
is INT, UINT,
FLOAT, COMPLEX and {BITS}
can be 8, 16, 32, 64, 80, 96, 128,
160, 192, 256, and 512. Obviously not all bitwidths are available on
all platforms for all the kinds of numeric types. Commonly 8, 16,
32, 64bit integers; 32, 64bit floats; and 64, 128bit complex
types are available.
Further integer aliases#
The constants NPY_INTP and NPY_UINTP refer to an Py_ssize_t
and size_t
.
Although in practice normally true, these types are strictly speaking not
pointer sized and the character codes 'p'
and 'P'
can be used for
pointer sized integers.
(Before NumPy 2, intp
was pointer size, but this almost never matched
the actual use, which is the reason for the name.)
Since NumPy 2, NPY_DEFAULT_INT is additionally defined.
The value of the macro is runtime dependent: Since NumPy 2, it maps to
NPY_INTP
while on earlier versions it maps to NPY_LONG
.
Ctype names#
There are standard variable types for each of the numeric data types and the bool data type. Some of these are already available in the Cspecification. You can create variables in extension code with these types.
Boolean#
(Un)Signed Integer#
Unsigned versions of the integers can be defined by prepending a ‘u’ to the front of the integer name.

type npy_byte#
char

type npy_ubyte#
unsigned char

type npy_short#
short

type npy_ushort#
unsigned short

type npy_int#
int

type npy_uint#
unsigned int

type npy_int16#
16bit integer

type npy_uint16#
16bit unsigned integer

type npy_int32#
32bit integer

type npy_uint32#
32bit unsigned integer

type npy_int64#
64bit integer

type npy_uint64#
64bit unsigned integer

type npy_long#
long int

type npy_ulong#
unsigned long int

type npy_longlong#
long long int

type npy_ulonglong#
unsigned long long int

type npy_intp#
Py_ssize_t
(a signed integer with the same size as the Csize_t
). This is the correct integer for lengths or indexing. In practice this is normally the size of a pointer, but this is not guaranteed.Note
Before NumPy 2.0, this was the same as
Py_intptr_t
. While a better match, this did not match actual usage in practice. On the Python side, we still supportnp.dtype('p')
to fetch a dtype compatible with storing pointers, whilen
is the correct character for thessize_t
.

type npy_uintp#
The C
size_t
/Py_size_t
.
(Complex) Floating point#

type npy_half#
16bit float

type npy_float#
32bit float

type npy_cfloat#
32bit complex float

type npy_double#
64bit double

type npy_cdouble#
64bit complex double

type npy_longdouble#
long double

type npy_clongdouble#
long complex double
complex types are structures with .real and .imag members (in that order).
Bitwidth names#
There are also typedefs for signed integers, unsigned integers, floating point, and complex floating point types of specific bit widths. The available type names are
npy_int{bits}
,npy_uint{bits}
,npy_float{bits}
, andnpy_complex{bits}
where {bits}
is the number of bits in the type and can be 8,
16, 32, 64, 128, and 256 for integer types; 16, 32
, 64, 80, 96, 128, and 256 for floatingpoint types; and 32,
64, 128, 160, 192, and 512 for complexvalued types. Which
bitwidths are available is platform dependent. The bolded bitwidths
are usually available on all platforms.
Time and timedelta#
Printf formatting#
For help in printing, the following strings are defined as the correct format specifier in printf and related commands.

NPY_LONGLONG_FMT#

NPY_ULONGLONG_FMT#

NPY_INTP_FMT#

NPY_UINTP_FMT#

NPY_LONGDOUBLE_FMT#