numpy arrays introduction content is everywhere, but most of it jumps straight to syntax without explaining why NumPy exists in the first place. This python numpy tutorial covers that "why" first — the actual memory and performance reasons NumPy arrays outperform plain Python lists for numerical work — before covering creation, core attributes, vectorized operations, and honest guidance on when a plain list is still the right choice.
Why NumPy Exists Alongside Python Lists
What NumPy is for
NumPy stands for Numerical Python, and it's used for handling large, multi-dimensional arrays and matrices, offering considerably more efficient storage and faster processing than Python's built-in lists for genuinely numerical work.
The core reason for the speed difference
This is the part most introductory guides skip, but it's worth understanding properly: a Python list doesn't actually store its values directly — it stores references to objects that live scattered elsewhere in memory. Every single loop iteration over a list involves following one of these references, then dealing with Python-level object overhead (type checking, reference counting) for each individual item. A NumPy array stores its actual data completely differently.
Contiguous memory: locality of reference
NumPy arrays are stored at one continuous place in memory, unlike lists, whose elements can be scattered anywhere. This property — called locality of reference — means a process can access and manipulate the data very efficiently: the CPU can read a large, contiguous block of memory directly, taking advantage of low-level optimizations (like CPU cache lines and vectorized CPU instructions) that simply aren't available when data is scattered across memory as a list of individually-boxed Python objects. This single structural difference is the real, underlying reason NumPy is dramatically faster for numerical work — not just a matter of convenient syntax.
Installing NumPy and Creating Your First Array
Installation
pip install numpy
As covered in the earlier virtual environments article, it's good practice to install NumPy inside a project-specific virtual environment, rather than globally.
The ndarray: NumPy's core data structure
At its core, NumPy provides the ndarray — short for n-dimensional array — used to store many items of the same data type efficiently. That last part is genuinely important and worth contrasting with Python lists directly: a Python list can freely mix an integer, a string, and a custom object all in the same list; a NumPy array is built around the assumption that every element shares the same type, which is precisely what enables the efficient, contiguous memory layout described above.
Creating a 1D array
import numpy as np
arr = np.array([1, 2, 3, 4, 5])
print(arr) # [1 2 3 4 5]
print(type(arr)) # <class 'numpy.ndarray'>np.array() converts a plain Python list into a NumPy array. import numpy as np is close to a universal convention — you'll see np. used as the prefix in essentially every piece of NumPy code you encounter.
Creating a 2D array
matrix = np.array([[1, 2, 3], [4, 5, 6]])
print(matrix)
# [[1 2 3]
# [4 5 6]]Passing a list of lists creates a 2D array — conceptually a matrix, with rows and columns — rather than a flat, one-dimensional sequence.
Specifying dtype explicitly
int_array = np.array([1, 2, 3], dtype="int")
float_array = np.array([1, 2, 3], dtype="float")
bool_array = np.array([1, 0, 1], dtype="bool")
print(float_array) # [1. 2. 3.]
print(bool_array) # [ True False True]dtype lets you explicitly control the element type NumPy uses internally. Without specifying it, NumPy infers a reasonable type automatically from the input values — but being explicit is often worth doing deliberately, both for clarity and because it directly affects the array's memory footprint (a float64 array, for instance, uses considerably more memory per element than an int8 array would, for values that fit within that smaller range).
Array Dimensions and Core Attributes
From 1D to higher dimensions
A one-dimensional array stores elements in a single row, and it's the simplest, most commonly used type — but NumPy scales naturally to two-dimensional matrices, and further to three or more dimensions (useful for things like a stack of images, or time-series data indexed by multiple factors at once).
np.array([1, 2, 3])
two_d = np.array([[1, 2, 3], [4, 5, 6]])
three_d = np.array([[[1, 2], [3, 4]], [[5, 6], [7, 8]]])Key attributes worth inspecting
arr = np.array([[1, 2, 3], [4, 5, 6]])
print(arr.shape) # (2, 3) — 2 rows, 3 columns
print(arr.dtype) # int64 (or int32, depending on platform)
print(arr.ndim) # 2 — number of dimensions
print(arr.size) # 6 — total number of elements.shape— a tuple describing the array's dimensions.(2, 3)means 2 rows and 3 columns..dtype— the data type of the array's elements, covered above..ndim— the number of dimensions (1 for a flat array, 2 for a matrix, and so on)..size— the total count of elements across the entire array, regardless of shape.
These four attributes are genuinely worth checking constantly while working with NumPy — a huge share of real-world NumPy bugs come down to an array having an unexpected shape or dtype, and these attributes are the fastest way to confirm exactly what you're actually working with.
An important structural limitation
This is worth flagging early, since it catches people used to Python lists' flexibility off guard: once a NumPy array is created, its size can't grow — there's no equivalent of a list's .append() that resizes the array in place. Functions like np.append() exist, but they work by creating an entirely new array behind the scenes and copying the existing data into it, rather than genuinely growing the original array in place.
arr = np.array([1, 2, 3])
new_arr = np.append(arr, 4) # this creates a NEW array
print(arr) # [1 2 3] — the original is unchanged
print(new_arr) # [1 2 3 4]If your workflow genuinely involves frequent, incremental appending, a plain Python list (converted to a NumPy array only once you're done appending) is often the more efficient choice — repeatedly calling np.append() in a loop, each time silently creating a whole new array and copying everything into it, is considerably slower than it might first appear.
Vectorized Operations: Where NumPy Actually Wins
The headline feature: vectorization
This is NumPy's single most important practical advantage: arrays support vectorized operations, meaning an operation runs on every element at once, without an explicit Python-level loop.
arr = np.array([1, 2, 3, 4, 5])
result = arr + 2
print(result) # [3 4 5 6 7]Try the equivalent directly on a plain Python list, and it doesn't do what you might expect:
plain_list = [1, 2, 3, 4, 5]
result = plain_list + 2
# TypeError: can only concatenate list (not "int") to listA plain list has no built-in concept of "add this number to every element" — + on a list means concatenation, not element-wise addition. Achieving the same result with a plain list requires an explicit loop or list comprehension: [x + 2 for x in plain_list] — functionally correct, but running at ordinary Python-loop speed, without any of the underlying contiguous-memory, vectorized-instruction advantages covered in Section 1.
Indexing and slicing
arr = np.array([10, 20, 30, 40, 50])
print(arr[0]) # 10 — first element
print(arr[-1]) # 50 — last element, negative indexing works exactly like lists
print(arr[1:4]) # [20 30 40] — slicing works tooIndexing and slicing look almost identical to plain Python lists — but there's a subtle, genuinely important difference: slicing a NumPy array typically returns a view, not a copy, in most common cases. This means modifying a slice can modify the original array too:
arr = np.array([10, 20, 30, 40, 50])
sub = arr[1:4]
sub[0] = 999
print(arr) # [ 10 999 30 40 50] — the original changed too!Compare this to a plain Python list, where slicing always creates a genuinely independent copy — modifying the sliced copy never affects the original. This view-versus-copy distinction is a genuinely common source of confusion (and real bugs) for people transitioning from plain Python lists to NumPy, and it's worth testing directly, as shown above, until it feels intuitive.
A real-world payoff example: a distance matrix
Computing pairwise distances between many points is a classic case where the difference becomes dramatic. With plain Python loops:
import math
points = [(1, 2), (3, 4), (5, 6)] # imagine hundreds or thousands of these in practice
distances = []
for p1 in points:
row = []
for p2 in points:
dist = math.sqrt((p1[0] - p2[0]) ** 2 + (p1[1] - p2[1]) ** 2)
row.append(dist)
distances.append(row)With NumPy, using broadcasting (covered in more depth in a later article in this series):
import numpy as np
points = np.array([[1, 2], [3, 4], [5, 6]])
diff = points[:, np.newaxis, :] - points[np.newaxis, :, :]
distances = np.sqrt((diff ** 2).sum(axis=2))Both compute the exact same result — but the NumPy version runs the entire calculation at compiled C speed, operating on the whole array at once, rather than looping through individual Python-level operations millions of times over for a genuinely large dataset. For a small handful of points, the difference is negligible; for datasets with thousands of points (a common scale in real data science and machine learning work), the NumPy version can run over 100 times faster than the equivalent nested Python loops.
When to Reach for NumPy (and When a List Is Still Fine)
Why NumPy matters beyond just arrays
Understanding NumPy deeply pays off well beyond NumPy itself: pandas DataFrames (covered in a later article in this series) are built directly on top of NumPy arrays internally, SciPy extends NumPy's array model for scientific computing, and scikit-learn requires NumPy arrays as its fundamental data format for machine learning. Genuinely understanding how NumPy arrays work — their shape, dtype, and vectorized operations — makes every one of these downstream libraries considerably easier to learn, use correctly, and debug when something goes wrong.
Practical guidance
Reach for NumPy when you're working with large numeric datasets, doing repeated mathematical operations across many values, or feeding data directly into machine learning or data-science libraries that expect NumPy arrays as their native input format. A plain Python list remains perfectly fine — genuinely, not just as a beginner's fallback — for small collections, mixed-type data (NumPy arrays want a single consistent dtype; a list handles heterogeneous data naturally), or collections that are processed infrequently, where the setup and conversion overhead of NumPy wouldn't meaningfully pay off.
What's next
This article covers the foundation: what NumPy arrays are, why they're faster, their core attributes, and vectorized operations. Later articles in this series build directly on this foundation — array creation functions (np.zeros(), np.arange(), np.linspace(), and similar), indexing and slicing in genuine depth, reshaping arrays between different dimensional layouts, and the broadcasting rules that made the distance-matrix example above possible without an explicit loop at all.