See also
Data type objects
Array types and conversions between types#
NumPy supports a much greater variety of numerical types than Python does.This section shows which are available, and how to modify an array’s data-type.
NumPy numerical types are instances of numpy.dtype (data-type) objects, eachhaving unique characteristics. Once you have imported NumPy using importnumpy as np you can create arrays with a specified dtype using the scalartypes in the numpy top-level API, e.g. numpy.bool, numpy.float32, etc.
These scalar types as arguments to the dtype keyword that many numpy functionsor methods accept. For example:
>>> z = np.arange(3, dtype=np.uint8)>>> zarray([0, 1, 2], dtype=uint8)
Array types can also be referred to by character codes, for example:
>>> np.array([1, 2, 3], dtype='f')array([1., 2., 3.], dtype=float32)>>> np.array([1, 2, 3], dtype='d')array([1., 2., 3.], dtype=float64)
See Specifying and constructing data types for more information about specifying andconstructing data type objects, including how to specify parameters like thebyte order.
To convert the type of an array, use the .astype() method. For example:
>>> z.astype(np.float64) array([0., 1., 2.])
Note that, above, we could have used the Python float object as a dtypeinstead of numpy.float64. NumPy knows thatint refers to numpy.int_, bool meansnumpy.bool, that float is numpy.float64 andcomplex is numpy.complex128. The other data-types do not havePython equivalents.
To determine the type of an array, look at the dtype attribute:
>>> z.dtypedtype('uint8')
dtype objects also contain information about the type, such as its bit-widthand its byte-order. The data type can also be used indirectly to queryproperties of the type, such as whether it is an integer:
>>> d = np.dtype(int64)>>> ddtype('int64')>>> np.issubdtype(d, np.integer)True>>> np.issubdtype(d, np.floating)False
Numerical Data Types#
There are 5 basic numerical types representing booleans (bool), integers(int), unsigned integers (uint) floating point (float) andcomplex. A basic numerical type name combined with a numeric bitsize definesa concrete type. The bitsize is the number of bits that are needed to representa single value in memory. For example, numpy.float64 is a 64 bitfloating point data type. Some types, such as numpy.int_ andnumpy.intp, have differing bitsizes, dependent on the platforms(e.g. 32-bit vs. 64-bit CPU architectures). This should be taken into accountwhen interfacing with low-level code (such as C or Fortran) where the raw memoryis addressed.
Data Types for Strings and Bytes#
In addition to numerical types, NumPy also supports storing unicode strings, viathe numpy.str_ dtype (U character code), null-terminated byte sequences vianumpy.bytes_ (S character code), and arbitrary byte sequences, vianumpy.void (V character code).
All of the above are fixed-width data types. They are parameterized by awidth, in either bytes or unicode points, that a single data element in thearray must fit inside. This means that storing an array of byte sequences orstrings using this dtype requires knowing or calculating the sizes of thelongest text or byte sequence in advance.
As an example, we can create an array storing the words "hello" and"world!":
>>> np.array(["hello", "world!"])array(['hello', 'world!'], dtype='<U6')
Here the data type is detected as a unicode string that is a maximum of 6 codepoints long, enough to store both entries without truncation. If we specify ashorter or longer data type, the string is either truncated or zero-padded tofit in the specified width:
>>> np.array(["hello", "world!"], dtype="U5")array(['hello', 'world'], dtype='<U5')>>> np.array(["hello", "world!"], dtype="U7")array(['hello', 'world!'], dtype='<U7')
We can see the zero-padding a little more clearly if we use the bytes datatype and ask NumPy to print out the bytes in the array buffer:
>>> np.array(["hello", "world"], dtype="S7").tobytes()b'hello\x00\x00world\x00\x00'
Each entry is padded with two extra null bytes. Note however that NumPy cannottell the difference between intentionally stored trailing nulls and paddingnulls:
>>> x = [b"hello\0\0", b"world"]>>> a = np.array(x, dtype="S7")>>> print(a[0])b"hello">>> a[0] == x[0]False
If you need to store and round-trip any trailing null bytes, you will need touse an unstructured void data type:
>>> a = np.array(x, dtype="V7")>>> aarray([b'\x68\x65\x6C\x6C\x6F\x00\x00', b'\x77\x6F\x72\x6C\x64\x00\x00'], dtype='|V7')>>> a[0] == np.void(x[0])True
Advanced types, not listed above, are explored in sectionStructured arrays.
Relationship Between NumPy Data Types and C Data Data Types#
NumPy provides both bit sized type names and names based on the names of C types.Since the definition of C types are platform dependent, this means the explicitlybit sized should be preferred to avoid platform-dependent behavior in programsusing NumPy.
To ease integration with C code, where it is more natural to refer toplatform-dependent C types, NumPy also provides type aliases that correspondto the C types for the platform. Some dtypes have trailing underscore to avoidconfusion with builtin python type names, such as numpy.bool_.
Canonical Python API name | Python API “C-like” name | Actual C type | Description |
|---|---|---|---|
numpy.bool or numpy.bool_ | N/A |
| Boolean (True or False) stored as a byte. |
numpy.int8 | numpy.byte |
| Platform-defined integer type with 8 bits. |
numpy.uint8 | numpy.ubyte |
| Platform-defined integer type with 8 bits without sign. |
numpy.int16 | numpy.short |
| Platform-defined integer type with 16 bits. |
numpy.uint16 | numpy.ushort |
| Platform-defined integer type with 16 bits without sign. |
numpy.int32 | numpy.intc |
| Platform-defined integer type with 32 bits. |
numpy.uint32 | numpy.uintc |
| Platform-defined integer type with 32 bits without sign. |
numpy.intp | N/A |
| Platform-defined integer of size |
numpy.uintp | N/A |
| Platform-defined integer type capable of storing the maximumallocation size. |
N/A |
|
| Guaranteed to hold pointers. Character code only (Python and C). |
N/A |
|
| Guaranteed to hold pointers. Character code only (Python and C). |
numpy.int32 or numpy.int64 | numpy.long |
| Platform-defined integer type with at least 32 bits. |
numpy.uint32 or numpy.uint64 | numpy.ulong |
| Platform-defined integer type with at least 32 bits without sign. |
N/A | numpy.longlong |
| Platform-defined integer type with at least 64 bits. |
N/A | numpy.ulonglong |
| Platform-defined integer type with at least 64 bits without sign. |
numpy.float16 | numpy.half | N/A | Half precision float:sign bit, 5 bits exponent, 10 bits mantissa. |
numpy.float32 | numpy.single |
| Platform-defined single precision float:typically sign bit, 8 bits exponent, 23 bits mantissa. |
numpy.float64 | numpy.double |
| Platform-defined double precision float:typically sign bit, 11 bits exponent, 52 bits mantissa. |
| numpy.longdouble |
| Platform-defined extended-precision float. |
numpy.complex64 | numpy.csingle |
| Complex number, represented by two single-precision floats (real and imaginary components). |
numpy.complex128 | numpy.cdouble |
| Complex number, represented by two double-precision floats (real and imaginary components). |
| numpy.clongdouble |
| Complex number, represented by two extended-precision floats (real and imaginary components). |
Since many of these have platform-dependent definitions, a set of fixed-sizealiases are provided (See Sized aliases).
Array scalars#
NumPy generally returns elements of arrays as array scalars (a scalarwith an associated dtype). Array scalars differ from Python scalars, butfor the most part they can be used interchangeably (the primaryexception is for versions of Python older than v2.x, where integer arrayscalars cannot act as indices for lists and tuples). There are someexceptions, such as when code requires very specific attributes of a scalaror when it checks specifically whether a value is a Python scalar. Generally,problems are easily fixed by explicitly converting array scalarsto Python scalars, using the corresponding Python type function(e.g., int, float, complex, str).
The primary advantage of using array scalars is thatthey preserve the array type (Python may not have a matching scalar typeavailable, e.g. int16). Therefore, the use of array scalars ensuresidentical behaviour between arrays and scalars, irrespective of whether thevalue is inside an array or not. NumPy scalars also have many of the samemethods arrays do.
Overflow errors#
The fixed size of NumPy numeric types may cause overflow errors when a valuerequires more memory than available in the data type. For example,numpy.power evaluates 100 ** 9 correctly for 64-bit integers,but gives -1486618624 (incorrect) for a 32-bit integer.
>>> np.power(100, 9, dtype=np.int64)1000000000000000000>>> np.power(100, 9, dtype=np.int32)-1486618624
The behaviour of NumPy and Python integer types differs significantly forinteger overflows and may confuse users expecting NumPy integers to behavesimilar to Python’s int. Unlike NumPy, the size of Python’sint is flexible. This means Python integers may expand to accommodateany integer and will not overflow.
NumPy provides numpy.iinfo and numpy.finfo to verify theminimum or maximum values of NumPy integer and floating point valuesrespectively
>>> np.iinfo(int) # Bounds of the default integer on this system.iinfo(min=-9223372036854775808, max=9223372036854775807, dtype=int64)>>> np.iinfo(np.int32) # Bounds of a 32-bit integeriinfo(min=-2147483648, max=2147483647, dtype=int32)>>> np.iinfo(np.int64) # Bounds of a 64-bit integeriinfo(min=-9223372036854775808, max=9223372036854775807, dtype=int64)
If 64-bit integers are still too small the result may be cast to afloating point number. Floating point numbers offer a larger, but inexact,range of possible values.
>>> np.power(100, 100, dtype=np.int64) # Incorrect even with 64-bit int0>>> np.power(100, 100, dtype=np.float64)1e+200
Extended precision#
Python’s floating-point numbers are usually 64-bit floating-point numbers,nearly equivalent to numpy.float64. In some unusual situations it may beuseful to use floating-point numbers with more precision. Whether thisis possible in numpy depends on the hardware and on the developmentenvironment: specifically, x86 machines provide hardware floating-pointwith 80-bit precision, and while most C compilers provide this as theirlong double type, MSVC (standard for Windows builds) makeslong double identical to double (64 bits). NumPy makes thecompiler’s long double available as numpy.longdouble (andnp.clongdouble for the complex numbers). You can find out what yournumpy provides with np.finfo(np.longdouble).
NumPy does not provide a dtype with more precision than C’slong double; in particular, the 128-bit IEEE quad precisiondata type (FORTRAN’s REAL*16) is not available.
For efficient memory alignment, numpy.longdouble is usually storedpadded with zero bits, either to 96 or 128 bits. Which is more efficientdepends on hardware and development environment; typically on 32-bitsystems they are padded to 96 bits, while on 64-bit systems they aretypically padded to 128 bits. np.longdouble is padded to the systemdefault; np.float96 and np.float128 are provided for users whowant specific padding. In spite of the names, np.float96 andnp.float128 provide only as much precision as np.longdouble,that is, 80 bits on most x86 machines and 64 bits in standardWindows builds.
Be warned that even if numpy.longdouble offers more precision thanpython float, it is easy to lose that extra precision, sincepython often forces values to pass through float. For example,the % formatting operator requires its arguments to be convertedto standard python types, and it is therefore impossible to preserveextended precision even if many decimal places are requested. It canbe useful to test your code with the value1 + np.finfo(np.longdouble).eps.
