Introduction
Adding a single number to an array works because NumPy stretches the number to the array's shape. Broadcasting generalises that idea: NumPy can combine a matrix with a row, a column with a row, or a stack of images with one colour, as long as the shapes fit a simple rule. It is one of NumPy's most powerful features, and one of the main sources of shape errors, so it is worth knowing the rule exactly.
How it works
To combine two arrays, NumPy compares their shapes from the right, one dimension at a time. Two sizes fit if they are equal, or one of them is 1. A shape with fewer dimensions is padded with 1s on the left. Each size 1 is stretched to the other size, without copying any data. If any pair does not fit, NumPy raises an error.
m = np.array([[1, 2, 3], [4, 5, 6]]) # shape (2, 3)
row = np.array([10, 20, 30]) # shape (3,) -> (1, 3)
print(m + row)
# [[11 22 33]
# [14 25 36]]
col = np.array([[100], [200]]) # shape (2, 1)
print(m + col)
# [[101 102 103]
# [204 205 206]]
The row has shape (3,): padded to (1, 3), its 1 is stretched over both rows. The column has shape (2, 1): its 1 is stretched over the three columns. Two 1-D arrays can even make a table: a column of shape (3, 1) plus a row of shape (1, 4) broadcasts to (3, 4).
When the sizes clash, NumPy says so, listing the shapes:
np.ones((2, 3)) + np.ones(2)
# ValueError: operands could not be broadcast together with shapes (2,3) (2,)
Here (2,) lines up with the 3 on the right, not with the 2. To add one value per row you need a column: v[:, np.newaxis] or v.reshape(-1, 1) turns shape (2,) into (2, 1), which broadcasts. np.broadcast_shapes((3, 1), (1, 4)) gives (3, 4) and is a quick way to check a rule in your head.
Example
# A model of NumPy's broadcasting rule, and of adding a row and a column to a grid.
def broadcast_shape(s1, s2):
n = max(len(s1), len(s2))
s1 = (1,) * (n - len(s1)) + s1 # pad the shorter shape with 1s on the left
s2 = (1,) * (n - len(s2)) + s2
out = []
for a, b in zip(s1, s2):
if a != b and a != 1 and b != 1:
return None # NumPy raises ValueError here
out.append(max(a, b))
return tuple(out)
for s1, s2 in [((2, 3), (3,)), ((3, 1), (1, 4)), ((2, 3), (2,)), ((4, 1, 5), (3, 1))]:
print(s1, "and", s2, "->", broadcast_shape(s1, s2) or "error")
grid = [[1, 2, 3], [4, 5, 6]]
row = [10, 20, 30] # shape (3,): stretched down the rows
print("grid + row:", [[x + r for x, r in zip(g, row)] for g in grid])
column = [100, 200] # shape (2, 1): stretched across the columns
print("grid + column:", [[x + c for x in g] for g, c in zip(grid, column)])Line by line
broadcast_shapepads the shorter shape with 1s on the left, as NumPy does.- It compares sizes pair by pair: equal or 1 fits, and the result takes the larger.
(2, 3)with(2,)fails, because the 2 lines up with the 3.- The grid examples stretch a row down the rows and a column across the columns.
Expected result
(2, 3) and (3,) -> (2, 3)
(3, 1) and (1, 4) -> (3, 4)
(2, 3) and (2,) -> error
(4, 1, 5) and (3, 1) -> (4, 3, 5)
grid + row: [[11, 22, 33], [14, 25, 36]]
grid + column: [[101, 102, 103], [204, 205, 206]]
In the real world
Centring data, X - X.mean(axis=0), broadcasts a row of column means over every row. Normalising images divides by a per-channel value of shape (3,) against images of shape (height, width, 3). Distance tables between two sets of points broadcast a column of points against a row of points. All of this runs without loops and without copying the smaller array.
Common mistakes
- Adding a per-row value of shape (n,) to an
(n, m)matrix, which lines up with the columns instead. - Broadcasting by accident:
(3,)minus(3, 1)gives a 3 by 3 table, not three differences. - Reading shapes from the left instead of the right.
- Using np.tile or loops to copy data when broadcasting would stretch it for free.
Best practices
- Write the shapes down and line them up from the right before combining arrays.
- Make columns explicit with
reshape(-1, 1)ornp.newaxis. - Check surprising results with
.shape, and withnp.broadcast_shapesbefore running.
Summary
Broadcasting compares shapes from the right; each pair must be equal or contain a 1, missing dimensions count as 1, and size-1 dimensions are stretched without copying. It lets matrices combine with rows, columns and single values, and an incompatible pair raises a ValueError listing both shapes.
Quick check
Key takeaways
- Line shapes up from the right; each pair of sizes must be equal, or one of them 1.
- A size-1 dimension is stretched to match; a missing dimension counts as 1.
- Turn a 1-D array into a column with v[:, np.newaxis] or v.reshape(-1, 1).
Practice problems for this lesson
My notes
Write down what you want to remember from this lesson. Notes are saved on this device as you type, and appear on your dashboard.