numpy vstack: Syntax, Shape Rules and Examples

numpy.vstack(tup, *, dtype=None, casting='same_kind') stacks arrays on top of each other, row by row, and returns an array that is at least two-dimensional. The rule that decides whether a call works is short: the arrays must have the same shape along every axis except the first, and one-dimensional arrays must have the same length. The one-dimensional case is the one people trip over, because vstack first turns a shape (N,) array into shape (1,N).

This guide follows the NumPy v2.5 manual, checked 2026-10-29. It covers the shape rule, the two official examples side by side, the exact error you get when shapes disagree, and how vstack relates to np.concatenate, np.stack and np.block.

What numpy vstack is used for in research code

Analysis scripts often build a results table one observation at a time: one array per participant, per sample or per simulation run, each holding the same measurements. np.vstack joins those into a single matrix with one row per item. The manual describes it as “Stack arrays in sequence vertically (row wise)” and notes that it rebuilds arrays that were divided by vsplit.

Install or access

NumPy’s install page (numpy.org/install) lists two routes. With pip: pip install numpy. With conda: create and activate an environment (conda create -n my-env, then conda activate my-env), then run conda install numpy. If you prefer a virtual environment, create it with python -m venv my-env and activate it (source my-env/bin/activate on macOS and Linux, my-env\Scripts\activate on Windows) before running pip install numpy. Then check the install:

import numpy as np
print(np.__version__)

Step by step: stacking arrays with np.vstack

Syntax and parameters

The first argument, tup, is a sequence of arrays, so the arrays go inside one pair of brackets or parentheses: np.vstack((a, b)), not np.vstack(a, b). The manual says the arrays “must have the same shape along all but the first axis” and that “1-D arrays must have the same length”. If you pass a single array-like, it is treated as a sequence of arrays: each element along the zeroth axis is handled as a separate array. Two keyword-only parameters were added in NumPy 1.24: dtype sets the dtype of the result (it cannot be combined with out), and casting controls what data casting may occur, with options ‘no’, ‘equiv’, ‘safe’, ‘same_kind’ and ‘unsafe’ and a default of ‘same_kind’.

Import NumPy. import numpy as np
Stack two one-dimensional arrays. With a = np.array([1, 2, 3]) and b = np.array([4, 5, 6]), np.vstack((a, b)) returns array([[1, 2, 3], [4, 5, 6]]), a 2×3 array. Each input became one row.
Stack two column arrays. With a = np.array([[1], [2], [3]]) and b = np.array([[4], [5], [6]]), np.vstack((a, b)) returns a single column holding 1 to 6, a 6×1 array. These inputs were already two-dimensional, so nothing was reshaped and the rows were simply placed one after the other.
Add a row to an existing matrix. A 2×3 array stacked with a one-dimensional array of length 3 gives a 3×3 array, because the length-3 array is first reshaped to (1,3). This is the usual pattern for growing a results matrix. Assign the result, since vstack returns a new array: results = np.vstack((results, new_row)).
Optionally set the dtype. np.vstack((a, b), dtype=float) returns the same rows as float64 values (NumPy 1.24 or later).

The shape rule at a glance

Inputs	What vstack does	Result
Two 1-D arrays of length 3, shape (3,)	Reshapes each to (1,3), then joins along the first axis	Shape (2,3)
Two 2-D arrays of shape (3,1)	Joins along the first axis	Shape (6,1)
1-D arrays of different lengths	Not allowed: 1-D arrays must have the same length	ValueError
Arrays that differ on any axis other than the first	Not allowed: shapes must match except along the first axis	ValueError

Output and how to read it

The result is always at least 2-D. The manual states that the stacked array “will be at least 2-D”, so even two short vectors come back as a matrix.
Rows follow the order of the sequence. The first array in tup supplies the first rows. To check, print .shape on the result: stacking arrays with n1 and n2 rows gives n1 + n2 rows, and the number of columns is unchanged.
It is equivalent to concatenation along the first axis. The manual says vstack is equivalent to np.concatenate(..., axis=0) after 1-D arrays of shape (N,) have been reshaped to (1,N). For arrays that are already two-dimensional, np.vstack((a, b)) and np.concatenate((a, b), axis=0) do the same job.

Troubleshooting

ValueError when the shapes do not match

Because every axis except the first must match, vstack of a length-3 array and a length-2 array fails. Running np.vstack(([1, 2, 3], [4, 5])) with NumPy 2.5.1 on 2026-10-29 raised: “ValueError: all the input array dimensions except for the concatenation axis must match exactly, but along dimension 1, the array at index 0 has size 3 and the array at index 1 has size 2”. The message names the dimension and the index of the array that disagrees. Fix the data so the lengths agree (for example by padding or trimming), or reconsider whether you want rows at all.

Two columns stacked into one long column

If you expected the second array to appear beside the first, you wanted columns, not rows. vstack always grows the first axis, so two (3,1) arrays become (6,1). For side-by-side joining, the manual’s See Also list points to hstack, column_stack and concatenate.

Passing the arrays as separate arguments

The signature takes one sequence, tup. Wrap the arrays in a tuple or list: np.vstack((a, b)).

Masked arrays lose their masks

The np.concatenate manual states that for masked arrays the input masks are not preserved and a MaskedArray is returned; it points to np.ma.concatenate for that case. Check this before using vstack on masked data, and use np.ma.concatenate to join masked arrays along the first axis.

Arrays with more than three dimensions

The manual says vstack “makes most sense for arrays with up to 3 dimensions” (its example is pixel data with height, width and r/g/b channels). For more general stacking, it recommends concatenate, stack and block.

Free alternatives: vstack compared with other NumPy functions

All of these ship with NumPy and are free. The table uses the one-line descriptions from the vstack manual’s See Also list.

Function	Manual description	Use it when
`np.vstack`	Stack arrays in sequence vertically (row wise)	You want rows added and 1-D inputs treated as single rows
`np.concatenate`	Join a sequence of arrays along an existing axis	You want to choose the axis; the default is `axis=0` and `axis=None` flattens first
`np.stack`	Join a sequence of arrays along a new axis	You want a new dimension, not a longer existing one
`np.block`	Assemble an nd-array from nested lists of blocks	You are building one array from blocks in a grid
`np.hstack`	Stack arrays in sequence horizontally (column wise)	You want columns added

For comparison, the concatenate manual gives np.concatenate((a, b), axis=0) with a = [[1, 2], [3, 4]] and b = [[5, 6]], which returns [[1, 2], [3, 4], [5, 6]].