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 type-character, 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 bit-width 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,
picks up a 32-bit float in C, but
in Python corresponds to a 64-bit double. The bit-width names can be used in both Python and C for clarity.
Enumerated types
enumNPY_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}:
enumeratorNPY_BOOL
The enumeration value for the boolean type, stored as one byte. It may only be set to the values 0 and 1.
enumeratorNPY_BYTE
enumeratorNPY_INT8
The enumeration value for an 8-bit/1-byte signed integer.
enumeratorNPY_SHORT
enumeratorNPY_INT16
The enumeration value for a 16-bit/2-byte signed integer.
enumeratorNPY_INT
enumeratorNPY_INT32
The enumeration value for a 32-bit/4-byte signed integer.
enumeratorNPY_LONG
Equivalent to either NPY_INT or NPY_LONGLONG, depending on the platform.
enumeratorNPY_LONGLONG
enumeratorNPY_INT64
The enumeration value for a 64-bit/8-byte signed integer.
enumeratorNPY_UBYTE
enumeratorNPY_UINT8
The enumeration value for an 8-bit/1-byte unsigned integer.
enumeratorNPY_USHORT
enumeratorNPY_UINT16
The enumeration value for a 16-bit/2-byte unsigned integer.
enumeratorNPY_UINT
enumeratorNPY_UINT32
The enumeration value for a 32-bit/4-byte unsigned integer.
enumeratorNPY_ULONG
Equivalent to either NPY_UINT or NPY_ULONGLONG, depending on the platform.
enumeratorNPY_ULONGLONG
enumeratorNPY_UINT64
The enumeration value for a 64-bit/8-byte unsigned integer.
enumeratorNPY_HALF
enumeratorNPY_FLOAT16
The enumeration value for a 16-bit/2-byte IEEE 754-2008 compatible floating point type.
enumeratorNPY_FLOAT
enumeratorNPY_FLOAT32
The enumeration value for a 32-bit/4-byte IEEE 754 compatible floating point type.
enumeratorNPY_DOUBLE
enumeratorNPY_FLOAT64
The enumeration value for a 64-bit/8-byte IEEE 754 compatible floating point type.
enumeratorNPY_LONGDOUBLE
The enumeration value for a platform-specific floating point type which is at least as large as NPY_DOUBLE, but larger on many platforms.
enumeratorNPY_CFLOAT
enumeratorNPY_COMPLEX64
The enumeration value for a 64-bit/8-byte complex type made up of two NPY_FLOAT values.
enumeratorNPY_CDOUBLE
enumeratorNPY_COMPLEX128
The enumeration value for a 128-bit/16-byte complex type made up of two NPY_DOUBLE values.
enumeratorNPY_CLONGDOUBLE
The enumeration value for a platform-specific complex floating point type which is made up of two NPY_LONGDOUBLE values.
enumeratorNPY_DATETIME
The enumeration value for a data type which holds dates or datetimes with a precision based on selectable date or time units.
enumeratorNPY_TIMEDELTA
The enumeration value for a data type which holds lengths of times in integers of selectable date or time units.
enumeratorNPY_STRING
The enumeration value for null-padded byte strings of a selectable size. The strings have a fixed maximum size within a given array.
enumeratorNPY_UNICODE
The enumeration value for UCS4 strings of a selectable size. The strings have a fixed maximum size within a given array.
enumeratorNPY_VSTRING
The enumeration value for UTF-8 variable-width 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 variable-width static strings to access the string data in each array entry.
Note
This DType is new-style and is not included in NPY_NTYPES_LEGACY.
enumeratorNPY_OBJECT
The enumeration value for references to arbitrary Python objects.
enumeratorNPY_VOID
Primarily used to hold struct dtypes, but can contain arbitrary binary data.
Some useful aliases of the above types are
enumeratorNPY_INTP
The enumeration value for a signed integer of type Py_ssize_t (same as ssize_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.
enumeratorNPY_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.
enumeratorNPY_MASK
The enumeration value of the type used for masks, such as with the
iterator flag. This is equivalent to
.
enumeratorNPY_DEFAULT_TYPE
The default type to use when no dtype is explicitly specified, for example when calling np.zero(shape). This is equivalent to
.
Other useful related constants are
NPY_NTYPES_LEGACY
The number of built-in 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 in NPY_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. New-style user DTypes currently are currently not assigned a type-number.
Note
The total number of user dtypes is limited to below NPY_VSTRING. Higher numbers are reserved to future new-style 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. 128-bit and 256-bit integers are rare).
NPY_MIN_{type}This is defined for {type} = BYTE, SHORT, INT, LONG, LONGLONG, INTP
NPY_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
Bit-width 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 bit-width 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 bit-widths are available on all platforms for all the kinds of numeric types. Commonly 8-, 16-, 32-, 64-bit integers; 32-, 64-bit floats; and 64-, 128-bit 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.
C-type 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 C-specification. You can create variables in extension code with these types.
Boolean
typenpy_bool
unsigned char; The constants
and
are also defined.
(Un)Signed Integer
Unsigned versions of the integers can be defined by prepending a ‘u’ to the front of the integer name.
typenpy_byte
char
typenpy_ubyte
unsigned char
typenpy_short
short
typenpy_ushort
unsigned short
typenpy_int
int
typenpy_uint
unsigned int
typenpy_int16
16-bit integer
typenpy_uint16
16-bit unsigned integer
typenpy_int32
32-bit integer
typenpy_uint32
32-bit unsigned integer
typenpy_int64
64-bit integer
typenpy_uint64
64-bit unsigned integer
typenpy_long
long int
typenpy_ulong
unsigned long int
typenpy_longlong
long long int
typenpy_ulonglong
unsigned long long int
typenpy_intp
Py_ssize_t (a signed integer with the same size as the C size_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 support np.dtype('p') to fetch a dtype compatible with storing pointers, while n is the correct character for the ssize_t.
typenpy_uintp
The C size_t/Py_size_t.
(Complex) Floating point
typenpy_half
16-bit float
typenpy_float
32-bit float
typenpy_cfloat
32-bit complex float
typenpy_double
64-bit double
typenpy_cdouble
64-bit complex double
typenpy_longdouble
long double
typenpy_clongdouble
long complex double
complex types are structures with .real and .imag members (in that order).
Bit-width 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}, and npy_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 floating-point types; and 32, 64, 128, 160, 192, and 512 for complex-valued types. Which bit-widths are available is platform dependent. The bolded bit-widths are usually available on all platforms.
Time and timedelta
typenpy_datetime
date or datetime (alias of
)
typenpy_timedelta
length of time (alias of
)
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