Python set.difference_update() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
set method

Definition

difference_update(*others) deletes from the set every item that appears in any of the iterables you pass. Items that are not in the set are simply ignored. The set is changed in place.

It does the same job as difference(), but instead of returning a new set it overwrites the original and returns None.

set.difference_update() is an instance method of the built-in set type: call it on a set with dot notation, such as subscribers.difference_update(...). No import is needed.

Syntax

Pass one or more iterables to subtract, and call it on its own line, because the return value is always None.

python
s.difference_update(iterable)
s.difference_update(iterable1, iterable2)
s -= other_set
CallWhat it does
{1, 2, 3}.difference_update({2})Returns None; the set becomes {1, 3}.
{1, 2, 3}.difference_update([1], (3,))Returns None; the set becomes {2}. Several iterables can be subtracted at once.
{1, 2}.difference_update(5)Raises TypeError: an int is not iterable.

s -= other has the same effect, but needs another set on the right. To remove a single item use discard() or remove(); to keep the original items and get a new set, use difference().

Method signatures
python
set.difference_update(*others)
# returns: None; every item found in any iterable is no longer in the set
# raises: TypeError if an argument is not iterable or an item is unhashable

Parameters

ParameterDescription
*othersZero or more iterables: set, list, tuple, string, range, and so on. Items found in any of them are removed from the set.

Return Value

Return ValueDescription
NoneAlways None. The set itself is smaller; it is empty (set()) if everything was removed.

Python Examples

Example 1 — Remove Unsubscribed Emails From a Mailing List

Subtract a list from a set, including an address that was never subscribed.

python
subscribers = {"[email protected]", "[email protected]", "[email protected]", "[email protected]"}
unsubscribed = ["[email protected]", "[email protected]"]

print(subscribers.difference_update(unsubscribed))
print(sorted(subscribers))
print(len(unsubscribed))

How It Works

  1. Changed in place. The method returns None and removes "[email protected]" from the set itself.
  2. An unknown address is ignored. "[email protected]" was never subscribed, and no KeyError is raised for it.
  3. The argument is unchanged. The list of unsubscribed addresses still has its two items.

Example 2 — Cross Finished Chores Off Several Lists

Subtract a set, a list, and a tuple in one call, then finish with the -= operator.

python
chores = {"dishes", "laundry", "vacuum", "trash", "dusting"}
done_morning = {"dishes"}
done_noon = ["trash", "vacuum"]
done_evening = ("laundry", "nap")

chores.difference_update(done_morning, done_noon, done_evening)
print(sorted(chores))

chores -= {"dusting"}
print(len(chores), chores)

How It Works

  1. Three lists in one call. Dishes, trash, vacuum, and laundry are removed; "nap" was never a chore, so it has no effect.
  2. One chore left. Only "dusting" is not in any of the three done lists.
  3. The operator form. chores -= {"dusting"} removes the last chore in place, leaving an empty set.
  4. An empty set prints as set(). The size is 0, and printing the set shows set().

Example 3 — Learn the Edge Cases of difference_update()

Subtract a set from itself, remove only some values, and call the method with no arguments.

python
ids = {10, 20, 30}
ids.difference_update(ids)
print(len(ids), ids)

ids.update([1, 2, 3, 4])
ids.difference_update([2, 4, 6])
print(sorted(ids))

ids.difference_update()
print(sorted(ids))

How It Works

  1. A set minus itself. Every item is also in the argument, so the set ends up empty.
  2. Partial removal. After adding 1 to 4 again, subtracting 2, 4, and 6 removes 2 and 4; 6 was never there.
  3. No arguments, no change. Calling difference_update() with nothing to subtract leaves 1 and 3 as they were.

Frequently Asked Questions

It removes from the set every item found in the arguments, changing the set in place. It returns None.
difference() returns a new set and leaves the original alone. difference_update() changes the original set and returns None.
No. Items that are not in the set are ignored, unlike remove(), which raises KeyError.
They have the same effect, but the -= operator needs a set on the right. difference_update() accepts any iterable and several arguments.
Pass the list to difference_update(), as in s.difference_update(my_list). There is no need to loop and call discard() for each item.

Next: set.discard()

Delete an item if it is in the set; do nothing if it is not.

discard() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

14 people found this page helpful