Python set.add() Method

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

Definition

add(item) puts one item into a set. The set is changed in place: no new set is created, and every name that refers to the set sees the new item.

A set keeps each value only once, so adding something that is already there does nothing and raises no error. The item must be hashable: numbers, strings, and tuples of those are fine, but a list, a dict, or another set raises TypeError.

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

Syntax

Pass the single item to add, and call it on its own line, because the return value is always None.

python
s.add(item)
CallWhat it does
{1, 2}.add(3)Returns None; the set becomes {1, 2, 3}.
{1, 2}.add(2)Returns None; the set becomes {1, 2}, unchanged because 2 is already there.
{1, 2}.add([3])Raises TypeError: a list is unhashable, so it cannot be a set item.

Adding is fast no matter how large the set is. To add several items at once use update(), or the |= operator with another set.

Method signatures
python
set.add(item)
# returns: None; item is now in the set (no change if it was already there)
# raises: TypeError if item is unhashable

Parameters

ParameterDescription
itemAny hashable object, added as a single element. Exactly one argument is required: add(1, 2) raises TypeError, and so does add([1, 2]).

Return Value

Return ValueDescription
NoneAlways None. The useful result is the set itself, which now contains the item.

Python Examples

Example 1 — Count Unique Visitors on a Website

Add every page hit to a set and see that repeat visitors are stored only once.

python
visitors = set()
for page_hit in ["u17", "u03", "u17", "u42", "u03", "u17"]:
    visitors.add(page_hit)

print(len(visitors))
print(sorted(visitors))
print(visitors.add("u99"))

How It Works

  1. Start empty. set() creates an empty set; writing {} would create an empty dict instead.
  2. Repeats vanish. Six hits are added, but "u17" and "u03" appear several times and are stored once, so the set holds three ids.
  3. Sorted for a stable print. A set has no fixed order, so sorted() turns the visitors into an alphabetical list.
  4. None, even for new ids. add() returns None whether or not the item was new, so "u99" prints None.

Example 2 — Tell New Tags From Existing Ones

Use in to report whether each tag is new, then add only the new ones.

python
tags = {"python", "sets"}

for tag in ["sets", "loops", "python", "loops"]:
    if tag in tags:
        print(tag, "already exists")
    else:
        tags.add(tag)
        print(tag, "added")

print(len(tags))

How It Works

  1. Membership first. tag in tags is a fast test, so you can tell the user whether a tag is new before changing the set.
  2. The first "loops" is new. It is not in the set yet, so add() stores it and the size grows from 2 to 3.
  3. The second "loops" is a repeat. The test now succeeds, so the message for an existing tag is printed.
  4. The check is only for the message. Calling add() again would be harmless too, because a duplicate never changes the set.

Example 3 — Remember Grid Cells a Robot Has Visited

Store coordinate pairs as tuples, then see why a list is rejected.

python
visited = set()
visited.add((0, 0))
visited.add((0, 1))
visited.add((0, 0))
print(len(visited), (0, 1) in visited)

try:
    visited.add([1, 1])
except TypeError:
    print("a list is not hashable")

visited.add(tuple([1, 1]))
print(sorted(visited))

How It Works

  1. Tuples work. A tuple of numbers is hashable, so (0, 0) and (0, 1) are accepted, and adding (0, 0) a second time keeps one copy.
  2. Lists are rejected. A list could change later, so Python refuses to hash it and add() raises TypeError.
  3. Convert, then add. tuple([1, 1]) makes an unchangeable (1, 1), which can be stored.
  4. Tuples sort item by item. sorted() compares the first numbers, then the second ones, giving (0, 0), (0, 1), (1, 1).

Frequently Asked Questions

It returns None. The set is changed in place, so call add() on its own line and do not assign its result to a variable.
Nothing happens and no error is raised. A set stores each value once, so the set keeps the same size.
Set items must be hashable, which means their value cannot change. Lists, dicts, and sets are mutable, so use a tuple or a frozenset instead.
Use update() with any iterable, such as s.update([1, 2, 3]), or the |= operator with another set. add() accepts exactly one item.
No. A set has no guaranteed order, so printing or looping may show items in a different order. Use sorted(s) when you need a stable order.

Next: set.clear()

Remove every item from the set, in place.

clear() →

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.

10 people found this page helpful