Python Overload Decorator: Multiple Type Signatures
Learn how to use Python's @overload decorator to define multiple type signatures, improving static type checking and code clarity.

When a function accepts several distinct input types and returns different types depending on the input, a single type annotation can only express the union of those return types. The @overload decorator from the typing module lets you declare multiple signatures for the same function, so static type checkers can infer the correct return type for each call. This article explains how to use @overload correctly, what it does and does not do, and how it compares to runtime dispatch mechanisms.
What the Overload Decorator Solves
Consider a function that converts a value to a string. A single annotation like def to_str(value: int | float) -> str works; it already tells the type checker that the return type is always str. That is sufficient when all inputs map to the same return type. The real problem arises when the return type depends on the input type in a more complex way, such as returning a list when given a list and a single value when given a scalar. Without overloads, the type checker has to assume the most general return type, which often loses information.
The @overload decorator exists to solve this by letting you define multiple type signatures for one function. Each signature describes a distinct combination of argument types and the corresponding return type. The actual implementation is written once, with no decorator, and must be compatible with all declared overloads.
Declaring Overloads with @overload
To use the decorator, import overload from typing. You then write multiple function definitions, each decorated with @overload, followed by a single implementation function that has no decorator. The overloaded definitions contain only the signature and a docstring or ... as the body. They are never executed at runtime.
from typing import overload
@overload
def parse(value: int) -> int: ...
@overload
def parse(value: str) -> str: ...
def parse(value):
if isinstance(value, int):
return value * 2
elif isinstance(value, str):
return value.upper()
else:
raise TypeError("Unsupported type")In this example, parse has two overloads: one for int returning int, and one for str returning str. The implementation function uses isinstance checks to handle both cases. At runtime, only the implementation exists; the overloaded definitions are ignored.
Writing the Implementation Function
The implementation function must be compatible with every overload. This means it must accept all argument types declared in the overloads, and its return type must be a union of the declared return types, or a supertype of them. The implementation should be written carefully to avoid runtime errors, especially because the overloaded stubs are not executed.
A common mistake is to put narrower annotations on the implementation than the overloads allow. For example, annotating the implementation as def parse(value: int) -> int is incompatible with the str overload. The implementation should either have no annotations or use a broad annotation such as def parse(value: int | str) -> int | str.
A Practical Example: Parsing Different Input Types
A more realistic scenario is a function that parses a configuration value. It might accept a string, a dictionary, or a list of strings, and return a structured object. Overloads let you express the exact return type for each input.
import json
from typing import Any, overload
@overload
def load_config(path: str) -> dict[str, Any]: ...
@overload
def load_config(data: dict[str, Any]) -> dict[str, Any]: ...
@overload
def load_config(paths: list[str]) -> list[dict[str, Any]]: ...
def load_config(source):
if isinstance(source, str):
with open(source) as f:
return json.load(f)
elif isinstance(source, dict):
return source
elif isinstance(source, list):
return [load_config(p) if isinstance(p, str) else p for p in source]
else:
raise TypeError("Unsupported source type")Here, the overloads tell the type checker that passing a string returns a single dictionary, passing a dictionary returns that dictionary, and passing a list of strings returns a list of dictionaries. Without overloads, the return type would have to be dict[str, Any] | list[dict[str, Any]], forcing callers to narrow the type manually.
How Type Checkers Resolve Overloads
Static type checkers like mypy, Pyright, and Pyre use overloads to select the correct signature for each call site. They evaluate the argument types in order and pick the first overload that matches. If none match, they report an error. This is why the order of overloads matters: put the most specific overloads first.
For example, if you have an overload for int and one for object, the int overload must come first. Otherwise, the object overload would match every integer, and the more specific one would never be used.
The resolution is purely static; it happens at type-check time, not at runtime. The @overload decorator has no effect on the function's behavior. It only exists in the type system.
Overload vs. functools.singledispatch
The @overload decorator is often confused with functools.singledispatch, which provides runtime dispatch based on the type of the first argument. The two serve different purposes: @overload is for type checking, while singledispatch is for actual runtime behavior.
| Aspect | typing.overload | functools.singledispatch |
|---|---|---|
| Purpose | Static type hints | Runtime dispatch |
| Execution | No runtime effect | Dispatches to registered functions |
| Type safety | Full type checking support | No type checking of return types |
| Use case | Multiple signatures for one function | Different implementations for different types |
You can combine both: use singledispatch to implement runtime behavior and @overload to provide precise type hints for the dispatch function. This is a common pattern in libraries that need both runtime flexibility and good type support.
Common Mistakes and Limitations
One common mistake is to put logic in the overloaded definitions. Since they are never executed, any code there is dead. Always use ... or a docstring as the body.
Another mistake is forgetting to include the implementation function. If you only have overloads and no implementation, the name is bound to a placeholder object rather than a callable function, so calls will fail at runtime.
Overloads also have limitations. Each overload describes one complete signature, so you have to list the combinations you want to support. They are resolved statically, not as runtime conditional dispatch. When you want to express relationships that apply across a family of types—for example, preserving the relationship between two arguments of the same type—a TypeVar with a bound, a Protocol, or a combination of overloads is often more maintainable than a long list of overloads.
Maintainability and Type Checker Compatibility
Adding overloads increases the surface area of your function's type contract. Every new overload must be kept in sync with the implementation, which adds maintenance overhead. If you extend the implementation to accept a new type and want precise return types for that new case, you need to add a matching overload.
Type checker compatibility is generally good, but there are subtle differences. Mypy and Pyright both support overloads, but the resolution algorithm can differ in edge cases, especially when overloads overlap. To avoid surprises, keep overloads disjoint or order them from specific to general. The @overload decorator has been part of the typing module since Python 3.5. The code examples use built-in generic types such as list[str] and dict[str, Any], which require Python 3.9 or later; on older Python versions, import List and Dict from typing.
When used correctly, @overload is a powerful tool for making your code easier to use and safer to refactor. It gives type checkers the information they need to catch errors at development time, without adding any runtime cost. The key is to treat overloads as a type-level contract and keep the implementation simple and focused.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.