set.union()

set.union(*others)

Returns: set · Updated March 15, 2026 · Set Methods

sets methods immutable

The .union() method returns a new set containing all unique elements from the original set and all other specified iterables. Unlike mutation methods like .update(), this leaves the original set unchanged.

Syntax

set.union(*others)

Parameters

Parameter	Type	Default	Description
`*others`	iterable	—	Any number of iterables (sets, lists, tuples, etc.) to combine with the original set.

Examples

Basic usage

Combine two sets to get all unique elements:

a = {1, 2, 3}
b = {3, 4, 5}
result = a.union(b)
print(result)
# {1, 2, 3, 4, 5}

The original sets remain unchanged:

x = {"apple", "banana"}
y = {"banana", "cherry"}
z = x.union(y)
print(x)  # {apple, banana} - unchanged
print(y)  # {banana, cherry} - unchanged
print(z)  # {apple, banana, cherry}

Using multiple arguments

Combine more than two sets at once:

set1 = {1, 2}
set2 = {2, 3}
set3 = {3, 4}
result = set1.union(set2, set3)
print(result)
# {1, 2, 3, 4}

Working with different iterables

Pass lists, tuples, or any iterable:

numbers = {1, 2, 3}
more_numbers = [4, 5, 6]
result = numbers.union(more_numbers)
print(result)
# {1, 2, 3, 4, 5, 6}

Using the | operator

The pipe operator is a convenient shorthand:

a = {1, 2}
b = {2, 3}
c = {3, 4}

# These are equivalent:
result1 = a.union(b, c)
result2 = a | b | c

print(result1)  # {1, 2, 3, 4}
print(result2)  # {1, 2, 3, 4}

Set comprehensions with union

Filter and combine in one expression:

evens = {x for x in range(10) if x % 2 == 0}
multiples_of_3 = {x for x in range(10) if x % 3 == 0}

result = evens.union(multiples_of_3)
print(sorted(result))
# [0, 2, 3, 4, 6, 8]

Common Patterns

Finding unique elements across datasets

users_tagged = {"alice", "bob", "charlie"}
users_commented = {"bob", "charlie", "diana"}
users_subscribed = {"charlie", "diana", "eve"}

all_users = users_tagged.union(users_commented, users_subscribed)
print(all_users)
# {alice, bob, charlie, diana, eve}

Combining feature sets

required_fields = {"id", "name", "email"}
optional_fields = {"phone", "address", "birth_date"}

all_fields = required_fields.union(optional_fields)
print(all_fields)
# {id, name, email, phone, address, birth_date}

Merging categories

python_topics = {"functions", "classes", "modules"}
web_topics = {"html", "css", "javascript"}
data_topics = {"pandas", "numpy"}

all_topics = python_topics.union(web_topics, data_topics)
print(all_topics)
# {functions, classes, modules, html, css, javascript, pandas, numpy}

vs update()

Remember the difference between union() and update():

colors = {"red", "blue"}
new_colors = {"blue", "green"}

# union() - returns new set, original unchanged
combined = colors.union(new_colors)
print(colors)    # {red, blue} - still here
print(combined) # {red, blue, green}

# update() - mutates original in-place
colors = {"red", "blue"}
colors.update(new_colors)
print(colors) # {red, blue, green} - modified

Performance

The .union() method:

Creates a new set with O(n) time complexity where n is the total number of elements
Each element is hashed once during the union operation
The original sets are not modified

For in-place modification, use .update() instead.