Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Tuple Type Hint: Syntax and Examples

Learn how to write precise tuple type hints in Python, from fixed-length records to variable-length sequences, with practical examples and edge cases.

~6 min readPython
#type hints#typing#tuples#mypy
Illustration of a Python tuple type hint showing a fixed-length tuple with integer and string elements.

When you annotate a function parameter or return value in Python, the tuple type hint has two distinct forms: a fixed-length record with a type for each position, and a variable-length sequence with a single element type. Choosing the wrong form is a common source of type-checker errors, so it helps to be explicit about which one you mean.

The syntax for a Python tuple type hint depends on whether the tuple's length is known at compile time. A fixed-length tuple, such as a coordinate pair or a database row, is annotated by listing the type of each element in order. A variable-length tuple, such as a collection of integers or strings, is annotated with a single type followed by an ellipsis. Mixing these forms or omitting the ellipsis leads to confusing errors in static type checkers.

The Two Shapes of a Tuple Type Hint

Python's tuple type can represent two different concepts: a heterogeneous record with a fixed number of fields, or a homogeneous sequence of arbitrary length. The type hint syntax reflects this distinction directly.

For a fixed-length tuple, you write the element types inside square brackets, separated by commas:

python
from typing import Tuple def split_name(full_name: str) -> Tuple[str, str]: first, last = full_name.split(" ", 1) return first, last

Here, Tuple[str, str] means a tuple with exactly two elements, both strings. The type checker will reject a return value that has a different length or an element of the wrong type.

For a variable-length tuple, you use a single type and an ellipsis:

python
from typing import Tuple def total(values: Tuple[int, ...]) -> int: return sum(values)

Tuple[int, ...] means a tuple of any length where every element is an int. The ellipsis is mandatory; Tuple[int] would mean a tuple with exactly one integer element, which is almost never what you want for a sequence.

Fixed-Length Tuples: One Type Per Position

Fixed-length tuples are most useful when the position of each element carries meaning. A common example is returning multiple values from a function, where each value has a distinct type.

python
def min_max(numbers: list[float]) -> tuple[float, float]: return min(numbers), max(numbers)

In this example, the return type tuple[float, float] tells the caller that the function returns two floats. The function name and implementation indicate that the first element is the minimum and the second is the maximum, but the type checker cannot enforce that order; that responsibility remains with the function implementation.

Fixed-length tuples can have more than two elements. For instance, a 3D point might be tuple[float, float, float], and a database row with an id, name, and timestamp might be tuple[int, str, datetime]. The type hint grows with the number of fields, which can become unwieldy. When a tuple has more than a few fields, consider using a NamedTuple or a dataclass instead.

Variable-Length Tuples: Homogeneous Elements

When a tuple is used as an immutable sequence, the type hint should reflect that all elements share a type. The ellipsis syntax tuple[T, ...] is the standard way to express this.

python
def first_and_last(items: tuple[str, ...]) -> tuple[str, str]: if not items: return "", "" return items[0], items[-1]

This function accepts a tuple of any length; the explicit empty-tuple check prevents an IndexError when items has no elements. As long as every element is a string, the return type is a fixed-length tuple with two strings.

Variable-length tuples are less common than lists in Python code, but they appear when immutability matters. For example, a configuration value that should not be modified after creation is often stored as a tuple. The type hint tuple[str, ...] communicates that the value is a sequence of strings and that callers should not attempt to mutate it.

Using typing.Tuple vs the Built-in tuple

Since Python 3.9, the built-in tuple can be used directly in type hints, and the typing.Tuple alias is no longer necessary for new code. The syntax is identical:

python
# Python 3.9+ def pair() -> tuple[int, str]: return 1, "one"
python
# Python 3.8 and earlier from typing import Tuple def pair() -> Tuple[int, str]: return 1, "one"

If you are targeting Python 3.9 or later, prefer the built-in tuple for consistency with other built-in types like list and dict. If you need to support older versions, use typing.Tuple. Modern type checkers such as mypy and Pyright handle both forms correctly.

Both typing.Tuple and the built-in tuple support the same parameters in Python 3.9+. There is no functional difference beyond version compatibility, so the shorter built-in form is preferred for new code.

NamedTuple: Typed Records With Field Names

When a tuple represents a record with named fields, a NamedTuple provides better readability and type safety than a bare tuple type hint. A NamedTuple is a subclass of tuple that adds field names and per-field types.

python
from typing import NamedTuple class Point(NamedTuple): x: float y: float def midpoint(a: Point, b: Point) -> Point: return Point((a.x + b.x) / 2, (a.y + b.y) / 2)

Here, Point is a tuple with two float fields. The type hint Point is more descriptive than tuple[float, float], and accessing a.x is clearer than a[0]. The type checker can verify that the correct fields are used and that the return value is a Point.

NamedTuple also supports default values and docstrings, making it a lightweight alternative to a dataclass when you want tuple semantics such as unpacking and immutability.

Common Edge Cases and Mistakes

The most frequent mistake with tuple type hints is forgetting the ellipsis for a variable-length tuple. Writing tuple[int] instead of tuple[int, ...] creates a fixed-length tuple with one element, which will cause type errors when the function is called with a tuple of a different length.

Another edge case is the empty tuple. The type hint for an empty tuple is tuple[()] (or Tuple[()] if you are using the older typing form). However, if a function can receive an empty tuple as well as tuples with elements, tuple[T, ...] already includes the empty tuple, so it is usually more appropriate. If you truly need to restrict a value to the empty tuple, tuple[()] is the correct annotation.

A third issue is mixing fixed and variable parts. The simple tuple[int, str, ...] syntax is not valid. In Python 3.11+, you can express a fixed prefix followed by a variable tail with the variadic tuple form tuple[int, *tuple[str, ...]]. For most code, however, a NamedTuple with an additional list or tuple field is often clearer.

Runtime Behavior and Type Checker Compatibility

Type hints are not enforced at runtime in Python. The tuple type hint does not change how tuples behave; it only provides information to static type checkers and IDEs. This means a function annotated with tuple[int, str] will still accept a tuple with a string and an integer at runtime, unless you add explicit runtime validation.

For static checking, both mypy and Pyright understand the standard tuple type hint syntax. They will catch mismatched lengths and element types in assignments and return statements. However, they do not check the order of elements in a fixed-length tuple beyond the declared types. If you need to enforce that the first element is always the minimum, that logic must be in the implementation.

Modern versions of mypy and Pyright handle typing.Tuple and the built-in tuple interchangeably, so migration between the two is straightforward.

When a Tuple Type Hint Is the Right Choice

Choosing between a tuple type hint and a list type hint comes down to mutability and semantic intent. A tuple is immutable, so a tuple[int, ...] tells the caller that the sequence will not be modified. A list type hint list[int] allows the function to modify the list in place, which may be desirable or not depending on the contract.

For fixed-length records, a tuple type hint is concise and works well for small structures. When the record grows beyond a few fields, a NamedTuple or a dataclass is more maintainable because it gives names to the fields and reduces the chance of positional errors. Use a bare tuple type hint when the structure is simple and the meaning of each position is obvious from context.

A variable-length tuple type hint is appropriate for functions that accept or return an immutable sequence of homogeneous values. A tuple is also hashable when its elements are hashable, which makes it usable as a dictionary key or set element. If the function needs to append or remove elements, a list is more suitable, and the type hint should reflect that.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.