set.update()

The in-place union — take any iterable(s) and add every element. The bulk cousin of add().

Set methodPython 2.6+Live demo
Common call
seen.update(new_batch)
Returns
None — set is mutated with the new members
Replaces
a loop of `s.add(x) for x in iterable`
Watch out
accepts any iterable — sets, lists, strings, generators; the iterable itself is not stored
set.update(*others)
→ None

Demo

Live evaluation
Try:
Inputs
setsetexisting elements
othersetitems to add (iterable)
Output
{'a', 'b', 'c'}.update({'d', 'e', 'f'})
[{'a', 'b', 'c'}, {'d', 'e', 'f'}]

update mutates the set in place. Real Python returns None; the demo shows the RESULTING state so the effect is visible. Every element from the iterable that is not already present is added. Duplicates in the iterable collapse (they already do in a set). The iterable can be any iterable — a list, tuple, string, generator — not just another set.

Parameters

NameTypeRequiredDescription
*othersiterableno (())Zero or more iterables. Every element of each is added to the set. Iterables need not be sets — lists, tuples, generators, and strings all work.

Return value

None — Returns None. The set is mutated in place — every element from each iterable that is not already present is added. Equivalent to `s |= set(other1) | set(other2) | ...` but takes any iterables, not just sets.

Common patterns

Merge a batch of items
Add many elements from any iterable in one call.
seen.update(new_batch)
Multiple iterables at once
update takes *args — pass several iterables to add from all of them.
names.update(first_names, last_names, aliases)
The operator alternative
`|=` is equivalent when the RHS is a set. update is more flexible.
s |= other_set        # requires a set on the right
s.update(iterable)     # any iterable works
Build up from a generator
Feed lazy computation directly into the set.
s.update(f(x) for x in inputs if valid(x))

Examples

1. Basic
s = {1, 2} s.update([3, 4]) s
Returns
{1, 2, 3, 4}
2. Partial overlap
{1, 2, 3}.update({3, 4, 5})
Returns
{1, 2, 3, 4, 5}
3. From a string
s = set() s.update("abc") s
Returns
{"a", "b", "c"}
4. Multiple iterables
s.update([1, 2], [2, 3], [3, 4])
Returns
{1, 2, 3, 4}
5. From a generator
s.update(x * 2 for x in range(3))
Returns
{0, 2, 4}
6. Returns None
{1, 2}.update([3])
Returns
None

Pitfalls

1. update() returns None — do NOT assign the result
The classic bug that applies to every mutation method. `s = s.update(other)` sets s to None. Since Python returns None to signal side-effect operations, all in-place mutations follow this rule.
Assigned None
s = {1, 2}
s = s.update([3])
print(s)
None
Just call it
s.update([3])
print(s)
{1, 2, 3}
2. update mutates — copy first if the original matters
update is destructive — the original set is changed. If you need the pre-update state, copy first.
Original lost
before = s
s.update(new)
before is s
True — same object, both mutated
Snapshot copy
before = s.copy()
s.update(new)
before
preserved
3. A string is a sequence of characters
Passing a string to update adds each CHARACTER, not the string as a whole. Wrap in a list or tuple to add the string itself.
Broken into chars
s = set()
s.update("hi")
{"h", "i"} # not {"hi"}
Wrap the string
s.update(["hi"])
{"hi"}
4. Elements must be hashable — like every set operation
The iterable can contain any values that are hashable. Lists and dicts as elements raise TypeError.
List elements
s.update([[1, 2], [3, 4]])
TypeError: unhashable type: 'list'
Tuple elements
s.update([(1, 2), (3, 4)])
{(1, 2), (3, 4)}

When to use

Use it
  • Adding a batch of elements from any iterable
  • Merging many sets or lists into one
  • Building up a set from a stream or generator
  • Any time `for x in iterable: s.add(x)` would work — one call is faster and clearer
Reach for something else
  • You need a new set — use `|` or `union()` for a pure result
  • One element at a time → s.add(x) is clearer
  • Elements might be unhashable → filter or convert first
  • You want the result assigned back — the operator form (|=) makes intent explicit

Notes

Complexity
O(m + n) — proportional to the size of the iterable(s) plus final size of the set
Return
None; the set is mutated in place
CPython impl
Objects/setobject.c :: set_update
Memory
May reallocate the hash table when the set grows
Thread-safe
Not safe under concurrent iteration or mutation

FAQ

For a set on the right, they are equivalent: `s |= t` calls `s.update(t)`. But update accepts ANY iterable (list, string, generator) — the `|=` operator requires a set. update also accepts multiple iterables in one call.

History

2.6
set.update() supports multiple *args of iterables.
2.3
set added as a builtin type with update().