tuple()

A list that cannot change, and is hashable because of it. That hashability is usually the reason to reach for one.

Built-in function / typePython 1.0+Live demo
Common call
tuple(iterable)
Returns
a new tuple — immutable and hashable if its items are
Replaces
a list when the value must be a dict key or set member
Watch out
a one-item tuple needs the trailing comma: (x,) not (x)
tuple([iterable])
→ tuple

Demo

Live evaluation
Try:
Inputs
iterablestra string to split into characters
Output
tuple('abc')
('a', 'b', 'c')

tuple copies the items of an iterable into a fixed sequence, exactly like list but without the ability to change afterwards. Watch the one-character case: the result prints as ("x",) with a trailing comma, which is how Python distinguishes a one-item tuple from a parenthesised expression. The empty case prints as () with no comma needed.

Parameters

NameTypeRequiredDescription
iterableiterableno (())Any iterable — string, list, set, dict, generator. Omitted gives the empty tuple.

Return value

tuple — A new tuple holding the items of iterable in order. With no argument, the empty tuple.

Common patterns

Use a sequence as a dict key
The headline use — lists cannot be keys, tuples can.
cache[(x, y)] = compute(x, y)
Freeze a list before sharing it
Callers cannot mutate what they are given.
return tuple(self._items)
Group rows for uniqueness
Tuples hash, so a set of them deduplicates whole records.
unique_rows = {tuple(row) for row in rows}

Examples

1. From a string
tuple('abc')
Returns
('a', 'b', 'c')
2. One item
tuple('x')
Returns
('x',) # trailing comma
3. From a list
tuple([1, 2])
Returns
(1, 2)
4. Empty
tuple()
Returns
()
5. Usable as a key
d = {(1, 2): "point"} d[(1, 2)]
Returns
'point'
6. A list cannot be
d = {[1, 2]: "point"}
Returns
TypeError: unhashable type: 'list'

Pitfalls

1. A one-item tuple needs the trailing comma
Parentheses do not make a tuple — the comma does. (x) is just x in brackets, which silently gives the wrong type rather than an error.
Not a tuple
t = ('a')
type(t)
<class 'str'>
Add the comma
t = ('a',)
type(t)
<class 'tuple'>
2. Immutable does not mean unchangeable all the way down
The tuple fixes which objects it holds, not what those objects contain. A tuple with a list inside can still change, and it stops being hashable.
Inner list mutates
t = ([1], [2])
t[0].append(99)
t
([1, 99], [2])
Freeze all the way
t = ((1,), (2,))
hash(t)
hashable and stable
3. Hashable only if every item is
Tuples get their hash from their contents, so one unhashable element makes the whole tuple unhashable — usually discovered at the moment you try to use it as a key.
Contains a list
hash(([1], 2))
TypeError: unhashable type: 'list'
All hashable
hash(((1,), 2))
an int
4. A string still explodes into characters
Same trap as list. tuple("abc") is three elements, not one.
Per character
tuple('abc')
('a', 'b', 'c')
Wrap it
('abc',)
('abc',)

When to use

Use it
  • The value must be a dict key or a set member
  • Returning a sequence callers should not mutate
  • Fixed-shape records where the positions have meaning
  • Deduplicating whole rows via a set
Reach for something else
  • The contents will change → list
  • Fields deserve names → collections.namedtuple or a dataclass
  • You need uniqueness within the sequence → set or frozenset

Notes

Complexity
O(n) — every item is copied into the new tuple
Return
A new tuple; note that tuple(t) may return t itself when t is already a tuple
CPython impl
Objects/tupleobject.c :: tuple_new_impl
Memory
Allocates exactly n slots — no growth room, so slightly smaller than a list
Thread-safe
Yes — tuples are immutable

FAQ

Because tuples are immutable, copying one would be pointless — CPython returns the original when the argument is already a tuple. That is safe precisely because nothing can change it, and it is why tuple(t) is t may be True while list(l) is l never is.

t = (1, 2)
tuple(t) is t   # True

History

1.0
tuple has been a core built-in type since the earliest Python.
2.2
tuple became a true type usable as a base class, rather than a factory function.
2.6
Gained the count and index methods, completing the Sequence interface.