WOLFRAM

Wolfram Language & System Documentation Center

Join[list1,list2,…]

concatenates lists or other expressions that share the same head.

Join[list1,list2,…,n]

joins the objects at level n in each of the listi.

Details
Details and Options Details and Options
Examples  
Basic Examples  
Scope  
Generalizations & Extensions  
Applications  
Properties & Relations  
Neat Examples  
See Also
Tech Notes
Related Guides
Related Links
History
Cite this Page

Join

Join[list1,list2,…]

concatenates lists or other expressions that share the same head.

Join[list1,list2,…,n]

joins the objects at level n in each of the listi.

Details

  • The listi do not need to have head List, but must all have the same head.
  • Join works on Association objects, keeping the last value associated with any given key.
  • Join works on SparseArray objects by effectively concatenating the corresponding ordinary lists. »
  • Join[list1,list2,…,n] handles ragged arrays by effectively concatenating all successive elements at level n in each of the listi. »

Examples

open all close all

Basic Examples  (3)

Wolfram Language code: Join[{a, b, c}, {x, y}, {u, v, w}]

Infix syntax:

Wolfram Language code: {a, b, c}~Join~{x, y}~Join~{u, v, w}

Join two associations:

Wolfram Language code: Join[<|a -> b|>, <|c -> d, a -> e|>]

Scope  (4)

Join two matrices to make longer columns:

Wolfram Language code: Join[{{a, b}, {c, d}}, {{1, 2}, {3, 4}}]

Join columns of two matrices to make longer rows:

Wolfram Language code: Join[{{a, b}, {c, d}}, {{1, 2}, {3, 4}}, 2]

With ragged arrays, successive elements are effectively concatenated:

Wolfram Language code: Join[{{1}, {5, 6}}, {{2, 3}, {7}}, {{4}, {8}}, 2]

The second row comes from the concatenation of nothing with {3,4}:

Wolfram Language code: Join[{{x}}, {{1, 2}, {3, 4}}, 2]

Join depth 3 arrays at different levels:

Wolfram Language code: aa = Array[Subscript[a, #]&, {2, 2, 2}]; bb = Array[Subscript[b, #]&, {2, 2, 2}];
Wolfram Language code: Join[aa, bb]
Wolfram Language code: Join[aa, bb, 2]
Wolfram Language code: Join[aa, bb, 3]

Generalizations & Extensions  (2)

Join expressions with any head:

Wolfram Language code: Join[f[a, b, c], f[x, y], f[u, v, w]]

Join works with SparseArray objects:

Wolfram Language code: SparseArray[Range[5]]
Wolfram Language code: Join[%, %, %]

Applications  (2)

Augment a matrix by adding a row:

Wolfram Language code: Join[IdentityMatrix[3], {{1, 2, 3}}]//MatrixForm

Augment by a column:

Wolfram Language code: Join[IdentityMatrix[3], Transpose[{{1, 2, 3}}], 2]//MatrixForm

Make a block matrix:

Wolfram Language code: Join[Join[(⁠| | | | | :- | :- | :- | | a1 | a1 | a1 | | a2 | a2 | a2 | | a3 | a3 | a3 |⁠), (⁠| | | | | :- | :- | :- | | b1 | b1 | b1 | | b2 | b2 | b2 | | b3 | b3 | b3 |⁠), 2], Join[(⁠| | | | | :- | :- | :- | | c1 | c1 | c1 | | c2 | c2 | c2 | | c3 | c3 | c3 |⁠), (⁠| | | | | :- | :- | :- | | d1 | d1 | d1 | | d2 | d2 | d2 | | d3 | d3 | d3 |⁠), 2]]//MatrixForm

This can also be done with ArrayFlatten:

Wolfram Language code: ArrayFlatten[(⁠| | | | :-- | :-- | | (⁠\| \| \| \| \| :- \| :- \| :- \| \| a1 \| a1 \| a1 \| \| a2 \| a2 \| a2 \| \| a3 \| a3 \| a3 \|⁠) | (⁠\| \| \| \| \| :- \| :- \| :- \| \| b1 \| b1 \| b1 \| \| b2 \| b2 \| b2 \| \| b3 \| b3 \| b3 \|⁠) | | (⁠\| \| \| \| \| :- \| :- \| :- \| \| c1 \| c1 \| c1 \| \| c2 \| c2 \| c2 \| \| c3 \| c3 \| c3 \|⁠) | (⁠\| \| \| \| \| :- \| :- \| :- \| \| d1 \| d1 \| d1 \| \| d2 \| d2 \| d2 \| \| d3 \| d3 \| d3 \|⁠) |⁠)]//MatrixForm

Properties & Relations  (1)

Join[list1,list2,…] is equivalent to Flatten[{list1,list2,…},1]:

Wolfram Language code: Join[{1, 2}, {{a, b}, {c, d}}, {3, 4, 5}]
Wolfram Language code: Flatten[{{1, 2}, {{a, b}, {c, d}}, {3, 4, 5}}, 1]

Neat Examples  (2)

Successively double a list by joining to itself:

Wolfram Language code: NestList[Join[#, #]&, {x}, 4]

Build up the Thue–Morse sequence [more info]:

Wolfram Language code: NestList[Join[#, 1 - #]&, {1}, 5]
Wolfram Research (1988), Join, Wolfram Language function, https://reference.wolfram.com/language/ref/Join.html (updated 2014).

Text

Wolfram Research (1988), Join, Wolfram Language function, https://reference.wolfram.com/language/ref/Join.html (updated 2014).

CMS

Wolfram Language. 1988. "Join." Wolfram Language & System Documentation Center. Wolfram Research. Last Modified 2014. https://reference.wolfram.com/language/ref/Join.html.

APA

Wolfram Language. (1988). Join. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/Join.html

BibTeX

@misc{reference.wolfram_2026_join, author="Wolfram Research", title="{Join}", year="2014", howpublished="\url{https://reference.wolfram.com/language/ref/Join.html}", note=[Accessed: 12-June-2026]}

BibLaTeX

@online{reference.wolfram_2026_join, organization={Wolfram Research}, title={Join}, year={2014}, url={https://reference.wolfram.com/language/ref/Join.html}, note=[Accessed: 12-June-2026]}