set.difference_update()

The in-place difference — remove every element that appears in the given iterable(s). The bulk cousin of discard().

Set methodPython 2.6+Live demo
Common call
seen.difference_update(blocked)
Returns
None — set is mutated with the removals
Replaces
a loop of `s.discard(x) for x in iterable`
Watch out
accepts any iterable; elements not present are silently skipped (like discard, not remove)
set.difference_update(*others)
→ None

Demo

Live evaluation
Try:
Inputs
setsetexisting elements
othersetitems to remove (iterable)
Output
{'1', '2', '3', '4'}.difference_update({'2', '4'})
None

difference_update mutates the set in place. Real Python returns None; the demo shows the RESULTING state so the effect is visible. Every element that appears in the iterable is removed from the set. Elements in the iterable that are NOT in the set are silently ignored — no KeyError. The iterable can be any iterable, not just another set.

Parameters

NameTypeRequiredDescription
*othersiterableno (())Zero or more iterables. Every element appearing in any of them is removed from the set (if present).

Return value

None — Returns None. The set is mutated in place — every element that appears in any of the given iterables is removed. Equivalent to `s -= set(other1) | set(other2) | ...` but takes any iterables, not just sets.

Common patterns

Remove a batch of items
Drop many elements from any iterable in one call.
seen.difference_update(retired_ids)
Multiple iterables at once
difference_update takes *args — remove from any of several sources.
active.difference_update(banned, expired, deleted)
The operator alternative
`-=` is equivalent when the RHS is a set. difference_update is more flexible.
s -= other_set                # requires a set
s.difference_update(iterable)  # any iterable
Purge by predicate
Compute the to-remove set lazily, then subtract in place.
s.difference_update(x for x in s if is_stale(x))

Examples

1. Basic
s = {1, 2, 3, 4} s.difference_update([2, 4]) s
Returns
{1, 3}
2. Partial overlap
{"a", "b", "c"}.difference_update({"c", "d"})
Returns
{"a", "b"}
3. No overlap silent
{1, 2}.difference_update({3, 4})
Returns
{1, 2} # no error
4. Removes all
{"x"}.difference_update(["x"])
Returns
set()
5. Multiple iterables
s.difference_update([1, 2], [3, 4])
Returns
removes 1,2,3,4
6. Returns None
{1, 2}.difference_update([1])
Returns
None

Pitfalls

1. difference_update() returns None — do NOT assign the result
Same rule as every set mutation. Assigning the result sets your variable to None.
Assigned None
s = s.difference_update(other)
s is now None
Just call it
s.difference_update(other)
s is the updated set
2. Cannot iterate over set while mutating it
A subtle trap: passing the same set as the iterable would mutate what you are iterating. Python detects this and raises. Use a snapshot or a comprehension.
Self mutation
s.difference_update(s)
set() — but risky pattern
Snapshot
s.difference_update(list(s))
set() — clear intent
3. Silent on missing elements — no KeyError
Unlike set.remove(), difference_update silently ignores elements not in the set. This is usually the desired behavior for "bulk remove" but can hide bugs when you expected the element to be present.
Silent skip
{"a"}.difference_update(["z"])
{"a"} # z was not there, ignored
Check before if you care
missing = set(target) - s
if missing:
    log.warning(...)
4. A string is a sequence of characters
Passing a string removes each CHARACTER, not the string as a whole. Wrap in a list to target the string itself.
Broken into chars
s = {"h", "i", "no"}
s.difference_update("hi")
{"no"} # removed "h" and "i"
Wrap it
s.difference_update(["hi"])
unchanged if "hi" not in s

When to use

Use it
  • Removing many elements from a set given an iterable
  • Subtracting multiple sources in one call
  • Building a "keep" state by removing everything else
  • When silence on missing elements is desired (unlike remove())
Reach for something else
  • You need a new set — use `-` or `difference()` for a pure result
  • One element at a time → discard() is clearer
  • You need a KeyError on missing → build the check yourself first
  • You need to iterate over the removed items → compute the diff explicitly

Notes

Complexity
O(m) — proportional to the size of the iterable(s)
Return
None; the set is mutated in place
CPython impl
Objects/setobject.c :: set_difference_update
Memory
May shrink the hash table; usually keeps capacity
Thread-safe
Not safe under concurrent iteration or mutation

FAQ

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

History

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