Implementing Exponential Backoff with Python Tenacity
Configure exponential backoff retries in Python with Tenacity: wait_exponential, jitter, exception filtering, async support, and logging before retries.

Retrying a failed operation is straightforward, but retrying it the right way is not. If you immediately retry a request that just failed because the target service is overloaded, you add to the load instead of relieving it. Exponential backoff solves this by increasing the wait time between attempts. In Python, the Tenacity library turns this pattern into a decorator that you can apply to any function. This article shows how to configure exponential backoff with Tenacity in Python for reliable retry behavior.
Setting Up Tenacity for Retry Logic
Tenacity is a Python library that provides a declarative way to add retry behavior to functions. Install it with pip:
pip install tenacityThe core is the @retry decorator. At a minimum, you specify when to stop retrying and how long to wait between attempts. A basic retry that stops after three attempts and waits a fixed second looks like this:
from tenacity import retry, stop_after_attempt, wait_fixed
@retry(stop=stop_after_attempt(3), wait=wait_fixed(1))
def fetch_data():
# network call that may fail
passThis works, but a fixed wait is rarely the right choice for transient failures. If the service is struggling, a fixed wait can still pile up requests at the same moment. Exponential backoff spreads those attempts out.
Configuring Exponential Backoff with wait_exponential
Tenacity provides wait_exponential to generate wait times that grow exponentially. The core formula is multiplier * (exp_base ** n), capped by max, where n increases with each retry. The most commonly used parameters are:
multiplier– the base multiplier in secondsexp_base– the growth factor, default 2max– the maximum wait time in seconds
A typical configuration looks like this:
from tenacity import retry, stop_after_attempt, wait_exponential
@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, max=30))
def call_api():
# API call that may fail transiently
passBecause stop_after_attempt(5) allows five attempts total, this example produces four waits before the final attempt. With the default growth factor, those waits grow approximately as 1, 2, 4, and 8 seconds. The max=30 parameter keeps the delay from growing beyond 30 seconds if you increase the attempt limit, which is important when you have a deadline to meet.
You can also change the growth rate. For a slower increase, set exp_base to a value like 1.5. For a faster one, use 3. The right choice depends on how quickly the downstream service typically recovers.
Adding Jitter to Avoid the Thundering Herd
Even with exponential backoff, if many clients start at the same time, their retry attempts can synchronize and hit the service simultaneously. Jitter adds a random component to the wait time, breaking that synchronization.
Tenacity offers wait_random_exponential, which combines exponential growth with a random factor. The multiplier sets the base, and max caps the delay. The actual wait is randomly chosen between 0 and the computed exponential value.
from tenacity import retry, stop_after_attempt, wait_random_exponential
@retry(stop=stop_after_attempt(5), wait=wait_random_exponential(multiplier=1, max=30))
def fetch_resource():
# resource fetch that may fail
passThis is often the preferred approach for distributed systems because it reduces the chance of a coordinated retry storm. If you need full control, you can write a custom wait function that adds a fixed amount of jitter to the exponential value, but wait_random_exponential covers most use cases.
Retrying Only Specific Exceptions
By default, Tenacity retries on any exception. That is rarely what you want. A ValueError from bad input data will not be fixed by retrying, while a TimeoutError or a ConnectionError might be. Use retry_if_exception_type to narrow the retry condition.
from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
import requests
@retry(stop=stop_after_attempt(4), wait=wait_exponential(multiplier=1, max=20),
retry=retry_if_exception_type((requests.ConnectionError, requests.Timeout)))
def make_request():
response = requests.get("https://api.example.com/data")
response.raise_for_status()
return response.json()Here, only connection-level errors trigger a retry. HTTP errors like 404 or 500 are not retried unless you explicitly include them. You can also combine conditions with retry_if_exception_type and retry_if_result if you need to check the return value.
Using Exponential Backoff with Async Functions
Tenacity works with async functions out of the box. The decorator is applied the same way, but you need to await the function when calling it. The retry logic itself runs on the event loop, so it does not block the thread.
import asyncio
from tenacity import retry, stop_after_attempt, wait_exponential
@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=0.5, max=10))
async def fetch_async():
# async network call
pass
async def main():
await fetch_async()One thing to watch for is the interaction between retries and cancellation. If the coroutine is cancelled while waiting, Tenacity will propagate the cancellation. That is usually the desired behavior, but you should test it in your own context.
Observability and Logging During Retries
When a function is retried, you often want to know why it failed and how many attempts remain. Tenacity provides before_sleep callbacks that run before each wait. The before_sleep_log helper logs a message with the retry state.
import logging
from tenacity import retry, stop_after_attempt, wait_exponential, before_sleep_log
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
@retry(stop=stop_after_attempt(4), wait=wait_exponential(multiplier=1, max=20),
before_sleep=before_sleep_log(logger, logging.WARNING))
def flaky_call():
# function that may fail
passThe log message includes the number of attempts and the next wait time. For more detailed logging, you can write a custom before_sleep function that inspects the RetryCallState object, which contains the exception and the current attempt number.
Operational Considerations: When Exponential Backoff Is Not the Answer
Exponential backoff is a good default for transient failures, but it is not a cure-all. If the downstream service is down for maintenance or permanently misconfigured, retrying only delays the inevitable. You should always pair it with a stop condition, such as stop_after_attempt or stop_after_delay. A retry loop that never stops can tie up resources and mask the real problem.
Another consideration is the cost of each attempt. If the function is expensive, such as a large database query or a file upload, even a few retries can be costly. In that case, you might want a lower max wait and a smaller number of attempts.
Finally, exponential backoff is not a substitute for a circuit breaker. A circuit breaker stops all calls to a failing service for a period, preventing the retry storm from ever starting. Tenacity focuses on retry logic; for circuit breaking you would use a separate library or pattern. Use exponential backoff when you expect the failure to be short-lived, and combine it with monitoring so you know when retries are happening too often.
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.