Written and maintained by CASRAI Editorial Board
Published
On this page
numpy.hstack(tup, *, dtype=None, casting='same_kind') stacks arrays horizontally, column by column. Searched as “hstack numpy” or “numpy hstack”, it is the function you reach for when you have a measurement matrix and want to append more columns to it. The rule that decides whether a call works: the arrays must have the same shape along every axis except the second. One-dimensional arrays are the exception, because they are joined end to end along their only axis and can be any length.
This guide follows the NumPy v2.5 manual, read 2026-11-08. It covers the shape rule, the two official examples, a research-data example that shows the common one-dimensional trap, and how hstack differs from np.concatenate, np.column_stack and np.vstack.
What numpy hstack is used for in research code
Analysis scripts often hold measurements in one array and covariates (participant IDs, group codes, dose levels) in another, with one row per observation in both. np.hstack places them side by side into a single matrix. The manual describes it as stacking arrays in sequence horizontally (column wise), equivalent to concatenation along the second axis except for 1-D arrays, and notes that it rebuilds arrays divided by hsplit. It is most useful for arrays with up to three dimensions; for more general operations the manual points to concatenate, stack or block.
Install or access
NumPy’s install page (numpy.org/install) lists pip install numpy and, in a conda environment, conda install numpy. Then check the install:
import numpy as np
print(np.__version__)Step by step: stacking arrays with np.hstack
Syntax and parameters
The first argument, tup, is a sequence of arrays, so the arrays go inside one pair of brackets or parentheses: np.hstack((a, b)), not np.hstack(a, b). The manual says the arrays must have the same shape along all axes except the second, except 1-D arrays, which can be any length. A single array_like is treated as a sequence of arrays. Two keyword-only parameters were added in NumPy 1.24: dtype sets the dtype of the result (it cannot be used with out), and casting controls what data casting may occur, with a default of ‘same_kind’. The function returns the stacked ndarray.
- Import NumPy.
import numpy as np - Stack two one-dimensional arrays. With
a = np.array((1, 2, 3))andb = np.array((4, 5, 6)),np.hstack((a, b))returnsarray([1, 2, 3, 4, 5, 6]). The result is still one-dimensional: the arrays were joined end to end, not turned into columns. - Stack two column arrays. With
a = np.array([[1], [2], [3]])andb = np.array([[4], [5], [6]]),np.hstack((a, b))returnsarray([[1, 4], [2, 5], [3, 6]]), a 3×2 array.
Worked example: adding an ID column to a measurement matrix
Suppose X holds two measurements for three participants and ids holds their identifiers. The shapes below follow from the definitions; the printed values are what the documented rules produce.
X = np.array([[5.1, 3.2], [4.9, 3.0], [6.2, 3.4]]) # shape (3, 2)
ids = np.array([101, 102, 103]) # shape (3,)
np.hstack((X, ids)) # raises ValueError
np.hstack((X, ids.reshape(-1, 1))) # shape (3, 3)
np.column_stack((X, ids)) # same (3, 3) resultThe first call fails because X is two-dimensional and ids is one-dimensional, so the arrays cannot be joined along the second axis. Reshaping ids to a (3, 1) column fixes it. The result is [[5.1, 3.2, 101.], [4.9, 3.0, 102.], [6.2, 3.4, 103.]]: the integer IDs are upcast to float because the result must hold both. The manual’s column_stack page says 1-D arrays are turned into 2-D columns first, which is why the third call needs no reshape. If the IDs must stay integers, keep them in a separate array or a structured container rather than forcing a common dtype.
Output and how to read it
Check .shape on the result. For 2-D inputs the number of rows is unchanged and the number of columns is the sum of the input column counts. For 1-D inputs the length is the sum of the input lengths. Row i of every input must describe the same observation, because hstack aligns by position and does not check that the rows match.
Shape rules at a glance
| Inputs | Rule from the NumPy manual | Result |
|---|---|---|
| Two 1-D arrays | Concatenated along the first axis; lengths may differ | Longer 1-D array |
| Two 2-D arrays | Same number of rows; concatenated along the second axis | 2-D array, columns added |
| 2-D array and 1-D array | Shapes must match on all axes except the second, so a 1-D array does not qualify | ValueError; reshape the 1-D array to a column first |
Troubleshooting
ValueError when the shapes disagree
The cause is nearly always a row-count mismatch or a 1-D array mixed with a 2-D one. Print .shape for every input. For a 1-D array that should be a column, use arr.reshape(-1, 1) or switch to np.column_stack.
You expected a matrix and got a long 1-D array
Two 1-D arrays passed to hstack are joined end to end. To make them columns of a 2-D array use np.column_stack((a, b)), which for the manual’s example of (1,2,3) and (4,5,6) returns array([[1, 4], [2, 5], [3, 6]]).
Masks are lost
The np.concatenate manual page states that it does not preserve masking of masked arrays and points to np.ma.concatenate for that case.
hstack compared with related functions
| Function | What the manual says |
|---|---|
np.hstack(tup) |
Column-wise stacking; like concatenation along the second axis except 1-D arrays use the first axis |
np.concatenate(arrays, axis=0, ...) |
Joins along an existing axis you choose; all shapes must match except along that axis; axis=None flattens |
np.column_stack(tup) |
Turns 1-D arrays into 2-D columns first; 2-D arrays are stacked as-is, like hstack |
np.vstack(tup) |
The row-wise counterpart; see numpy vstack |
To add elements to a single array instead, see numpy append.
Free alternatives
NumPy itself is free, open-source software. Within it, the alternatives to hstack are the functions in the table above. For arrays with more than three dimensions, or for assembling blocks from nested lists, the manual recommends concatenate, stack or block. Arrays can also be created and reshaped as described in NumPy arrays, and shape mismatches between operands are a separate topic covered in NumPy broadcasting.
Reproducibility note
Record the NumPy version with np.__version__ in your analysis log, since the dtype and casting parameters exist only from 1.24. See computational reproducibility.
FAQ
What does np.hstack do?
It stacks arrays horizontally (column wise), equivalent to concatenation along the second axis, except that 1-D arrays are concatenated along the first axis.
What is the difference between hstack and concatenate?
hstack fixes the joining axis (the second, or the first for 1-D arrays). np.concatenate lets you choose the axis, and axis=1 on 2-D arrays gives the same result as hstack.
Can hstack join a 1-D array to a 2-D array?
Not directly. Reshape the 1-D array to a column with reshape(-1, 1) or use np.column_stack.
Sources
- NumPy manual, numpy.hstack (v2.5): numpy.org/doc/stable/reference/generated/numpy.hstack.html, read 2026-11-08.
- NumPy manual, numpy.concatenate: numpy.org/doc/stable/reference/generated/numpy.concatenate.html, read 2026-11-08.
- NumPy manual, numpy.column_stack: numpy.org/doc/stable/reference/generated/numpy.column_stack.html, read 2026-11-08.
- NumPy installation: numpy.org/install, read 2026-11-08.
