NumPy (Numerical Python) is the foundational package for n‑dimensional array computing & scientific computation in Python. ⚑ Current stable version: 2.2.5 (19 Apr 2025)
Why a 2.x branch?
Breaking API changes introduced in
2.0.0 (Sept 2024) modernised the dtype system, simplified legacy
behaviour, and aligned NumPy with PEP 684’s isolated interpreters. Key highlights:
StringDType
& extensible DType API np.int
, np.float
…)@
operator defaults to matrix‑multiply rules# CPython >= 3.9
python ‑m pip install ‑U numpy
Official wheels are compiled with OpenBLAS. For AVX‑512/ARM NEON tuned builds:
python ‑m pip install ‑U numpy‑{version}‑+mkl‑avx512‑cp310‑win_amd64.whl
git clone https://github.com/numpy/numpy
cd numpy
python ‑m pip install ‑r requirements.txt
python ‑m pip install ‑e .
ndarray
?shape
, dtype
, strides
, ndim
, itemsize
import numpy as np
arr = np.array([1, 2, 3], dtype=np.int32)
z = np.zeros((2, 3))
iden = np.eye(4, k=0) # identity
rnd = np.random.default_rng().normal(size=(2, 2))
arr.shape # (3,)
arr.ndim # 1
arr.dtype # int32
arr.strides # (4,) bytes between elements
DType
)NumPy ships signed/unsigned ints (8–64 bit), floats (16–128 bit), complex, bool, and datetime/timedelta.
StringDType
& Flexible types (2.x)
The new np.dtype("string") supports variable‑length UTF‑8
internally; brings parity with Pandas StringArray
.
from numpy.dtypes import DTypeMeta
class RGB8(np.dtype, metaclass=DTypeMeta):
def __new__(cls):
return np.dtype([("r","u1"),("g","u1"),("b","u1")])
arr[ start:stop:step ]
arr[:, 1] # column‑wise
arr[::‑1] # reverse
mask = arr % 2 == 0
arr[mask] # even numbers
idx = [np.newaxis, [0,2]]
arr[idx] # pick rows 0 & 2, keep rank
Slices are views; fancy‑indexing returns a copy.
Use arr.flags.writeable = False
to create a read‑only mmap‑safe view.
Broadcasting expands arrays of smaller shape to match larger
ones without copying.
Rules: align from the trailing dimension; dimensions of size 1 can
be stretched; mismatch leads to ValueError
.
a = np.arange(3) # shape (3,)
b = np.arange(6).reshape(2,3) # (2,3)
a + b # result shape (2,3)
ufunc
)
angles = np.linspace(0, 2*np.pi, 360)
y = np.sin(angles) # SIMD‑optimised
np.add.reduce(arr)
np.multiply.accumulate(arr)
np.subtract.outer(a, b)
def deg2rad(x): return x*np.pi/180
rad_ufunc = np.frompyfunc(deg2rad, 1, 1)
rad_ufunc([0, 90, 180])
NUMPY_EXPERIMENTAL_ARRAY_FUNCTION = 1
.np.lib.stride_tricks
for
windowing/rolling computations.%timeit
, py-spy
, or
np.benchmark (new in 2.1).
rolling = np.lib.stride_tricks.sliding_window_view(arr, window_shape=4)
means = rolling.mean(axis=-1)
numpy.linalg
)
A = np.random.default_rng().uniform(size=(3,3))
eigvals, eigvecs = np.linalg.eig(A)
q, r = np.linalg.qr(A)
x = np.linalg.solve(A, b)
np.linalg.svd(A, full_matrices=False)
NumPy delegates heavy linear algebra to BLAS/LAPACK. Compile with OpenBLAS, MKL or the high‑performance BLIS back‑end if you require multi‑threaded speed‑ups.
rng = np.random.default_rng(seed=42)
rng.integers(0, 10, size=5)
rng.normal(loc=0, scale=1, size=(2,2))
np.random.Generator.binomial
np.random.Generator.choice
For CPU‑vectorised descriptive statistics NumPy provides:
data.mean(axis=0)
np.nanmean(data)
data.std(ddof=1)
np.percentile(data, [25, 50, 75], method="nearest")
In 2.2 the nanquantile algorithm now supports
method="hazen"
& "weibull"
.
dt = np.dtype([("time","f8"),("lat","f4"),("lon","f4")])
gps = np.empty(1_000_000, dtype=dt)
gps["lat"] += 1.0 # vectorised field operation
Structured arrays behave like typed tables; each field is a view into the underlying buffer, enabling memory‑efficient column operations.
.npy
format
m = np.memmap("big.dat", dtype="float32", mode="r", shape=(10000, 10000))
NumPy forms the common array API baseline:
pandas
, xarray
, Polars
, scipy
,
scikit‑learn
, and GPU drops‑in (cupy
, torch.Tensor
)
all expose __array_interface__ or __array__.
Array API standard 2024 edition is fully supported in NumPy 2.1.
python ‑m numpy.f2py ‑‑check‑2‑compat project/
np.bool
, np.int
… aliasesnp.random.RandomState
with np.random.default_rng
Numpy 2.0 ABI
dtype=object
unless absolutely necessary__array_priority__
in subclassing to control op dispatchnp.isclose
over direct floating‑point equalitytyping ≈ ndarray[Any, Shape[N, M]]
) using
PEP 646 type hintsHappy vectorising!