Python set.difference() Method

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

Definition

difference(*others) builds a new set with the items of the set that do not appear in any of the iterables you pass. The original set is not changed.

Order matters: a.difference(b) keeps what only a has, while b.difference(a) keeps what only b has. With no arguments, you simply get a copy of the set.

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

Syntax

Pass one or more iterables to subtract, and keep the returned set in a variable.

python
rest = s.difference(iterable)
rest = s.difference(iterable1, iterable2)
rest = s - other_set
CallWhat it does
{1, 2, 3}.difference({2})Returns {1, 3}: the items of the set that are not in the argument.
{1, 2, 3}.difference([1], (3,))Returns {2}: items found in any argument are removed.
{1, 2}.difference({1, 2, 3})Returns set(): nothing of the first set is left, because the argument contains it all.

a - b is a shortcut for a.difference(b), but only between two sets. To remove the items from the existing set instead of making a new one, use difference_update().

Method signatures
python
set.difference(*others)
# returns: a new set with the items of the set that are in none of the iterables
# 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. An item is dropped if it appears in any of them.

Return Value

Return ValueDescription
setA new set with the remaining items. It is empty (set()) when everything was subtracted.

Python Examples

Example 1 — List the Library Books Not Yet Returned

Subtract the returned books from the borrowed ones, then swap the order.

python
borrowed = {"Dune", "Emma", "Ulysses", "Walden"}
returned = {"Emma", "Walden"}

overdue = borrowed.difference(returned)
print(sorted(overdue))
print(sorted(returned.difference(borrowed)))
print(len(borrowed))

How It Works

  1. What is still out. Removing Emma and Walden from the borrowed books leaves Dune and Ulysses.
  2. Swapping gives nothing. Every returned book was also borrowed, so returned.difference(borrowed) is empty and sorts to [].
  3. The original is untouched. The borrowed set still has four books, because difference() builds a new set.

Example 2 — Remove Several Groups of Users at Once

Subtract a set, a list, and a tuple in one call, and compare with chained - operators.

python
users = {"amy", "bob", "cal", "dee", "eve", "fay"}
admins = {"amy"}
banned = ["dee", "fay"]
bots = ("bob", "zed")

regular = users.difference(admins, banned, bots)
print(sorted(regular))
print(sorted(users - admins - set(banned) - set(bots)))

How It Works

  1. One call, three groups. Amy is an admin, Dee and Fay are banned, and Bob is a bot, so only Cal and Eve are left.
  2. Unknown names are fine. "zed" is not in users, so subtracting it changes nothing.
  3. The operator needs sets. The list and tuple are wrapped in set() so that - can be used, and the result is identical.

Example 3 — Compare Two Shopping Lists

See that the order of the sets matters, that an empty argument changes nothing, and that the - operator rejects a list.

python
home = {"milk", "eggs", "rice"}
store = {"eggs", "rice", "tea", "salt"}

print(sorted(store.difference(home)))
print(sorted(home.difference(store)))
print(sorted(home.difference([])))

try:
    home - ["milk"]
except TypeError:
    print("the - operator needs a set")

How It Works

  1. What to buy. The store has salt and tea that you do not have at home.
  2. What only you have. Swapping the sets lists milk, the one item missing from the store.
  3. An empty argument subtracts nothing. difference([]) returns all three home items.
  4. Operator versus method. home - ["milk"] raises TypeError because the right side is a list, while the method accepts one.

Frequently Asked Questions

A new set with the items that are in the set but not in any of the arguments. The original set is not changed.
Yes. a.difference(b) gives the items only in a, and b.difference(a) gives the items only in b. They are usually different sets.
difference() returns a new set and leaves the original alone. difference_update() removes the items from the original set and returns None.
Yes for two sets, but the - operator needs sets on both sides. The method also accepts lists, tuples, strings, and several arguments.
Use symmetric_difference() or the ^ operator. It returns the items from either set that are not in both.

Next: set.difference_update()

Remove every item found in the other iterables from the set, in place.

difference_update() →

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.

13 people found this page helpful