Skip to main content
`Ctrl`+`K`

# pandas.Index.union

final Index.union(other, sort=None)

  Form the union of two Index objects.

  If the Index objects are incompatible, both Index objects will be cast to dtype(‘object’) first.

  Parameters:
    other Index or array-like

      Index or an array-like object containing elements to form the union with the original Index.

    sort bool or None, default None

      Whether to sort the resulting Index.

      - None : Sort the result, except when

        1. self and other are equal.

        2. self or other has length 0.

        3. Some values in self or other cannot be compared. A RuntimeWarning is issued in this case.

      - False : do not sort the result.

      - True : Sort the result (which may raise TypeError).

  Returns:
    Index

      Returns a new Index object with elements from both the original Index and the `other` Index.

      If either index contains duplicate entries, the result preserves duplicates up to the maximum number of occurrences in either index.

  See also

  `Index.unique`

    Return unique values in the index.

  `Index.intersection`

    Form the intersection of two Index objects.

  `Index.difference`

    Return a new Index with elements of index not in other.

  Examples

  Union matching dtypes

      >>> idx1 = pd.Index([1, 2, 3, 4])
      >>> idx2 = pd.Index([3, 4, 5, 6])
      >>> idx1.union(idx2)
      Index([1, 2, 3, 4, 5, 6], dtype='int64')

  Union mismatched dtypes

      >>> idx1 = pd.Index(["a", "b", "c", "d"])
      >>> idx2 = pd.Index([1, 2, 3, 4])
      >>> idx1.union(idx2)
      Index(['a', 'b', 'c', 'd', 1, 2, 3, 4], dtype='object')

  Union with duplicate values

      >>> idx1 = pd.Index([1, 2, 2, 3])
      >>> idx2 = pd.Index([3, 3, 4])
      >>> idx1.union(idx2)
      Index([1, 2, 2, 3, 3, 4], dtype='int64')

  MultiIndex case

      >>> idx1 = pd.MultiIndex.from_arrays(
      ...     [[1, 1, 2, 2], ["Red", "Blue", "Red", "Blue"]]
      ... )
      >>> idx1
      MultiIndex([(1,  'Red'),
          (1, 'Blue'),
          (2,  'Red'),
          (2, 'Blue')],
         )
      >>> idx2 = pd.MultiIndex.from_arrays(
      ...     [[3, 3, 2, 2], ["Red", "Green", "Red", "Green"]]
      ... )
      >>> idx2
      MultiIndex([(3,   'Red'),
          (3, 'Green'),
          (2,   'Red'),
          (2, 'Green')],
         )
      >>> idx1.union(idx2)
      MultiIndex([(1,  'Blue'),
          (1,   'Red'),
          (2,  'Blue'),
          (2, 'Green'),
          (2,   'Red'),
          (3, 'Green'),
          (3,   'Red')],
         )
      >>> idx1.union(idx2, sort=False)
      MultiIndex([(1,   'Red'),
          (1,  'Blue'),
          (2,   'Red'),
          (2,  'Blue'),
          (3,   'Red'),
          (3, 'Green'),
          (2, 'Green')],
         )