Python __aexit__: Implementing Async Context Manager Exit
Learn how to implement Python's __aexit__ in async context managers, handle exceptions, and manage async resources with async with.

In Python's async context manager protocol, __aexit__ is the coroutine that runs when an async with block exits. It is responsible for cleanup and for deciding whether an exception raised inside the block should propagate. Understanding Python's __aexit__ is essential for writing robust asynchronous resource managers, such as database connections, network sockets, or file handles that require non-blocking teardown.
The Async Context Manager Protocol
The async context manager protocol consists of two methods: __aenter__ and __aexit__. Both methods must return awaitable objects, so they are almost always defined as coroutines using async def. When you write async with obj as resource:, Python calls await obj.__aenter__() to acquire the resource and then await obj.__aexit__(exc_type, exc, tb) when the block exits, regardless of whether an exception occurred.
The __aexit__ method receives three arguments: the exception type, the exception instance, and the traceback. If the block completes without an exception, all three are None. This mirrors the synchronous __exit__ method, but the async version must be awaited.
Implementing aexit: Signature and Return Value
The __aexit__ method receives its three arguments in a fixed order:
async def __aexit__(self, exc_type, exc, tb):
...The return value controls exception propagation. If __aexit__ returns True, the exception is suppressed and does not propagate out of the async with block. If it returns False or None, the exception propagates normally. When no exception occurred, the return value is ignored.
Here is a minimal implementation that closes an asynchronous resource:
class AsyncResource:
async def __aenter__(self):
await self.open()
return self
async def __aexit__(self, exc_type, exc, tb):
await self.close()
return False # Propagate any exceptionIn this example, close() is awaited, and the return value False ensures that exceptions from the async with block are not swallowed. If cleanup itself raises an exception, that exception replaces the original one, unless you explicitly handle it.
Exception Handling in aexit
One of the main reasons to implement __aexit__ is to handle exceptions that occur inside the async with block. You can inspect exc_type and exc and decide whether to suppress the exception or perform conditional cleanup.
For example, you might want to roll back a transaction only if an exception occurred:
class AsyncTransaction:
async def __aenter__(self):
await self.begin()
return self
async def __aexit__(self, exc_type, exc, tb):
if exc_type is not None:
await self.rollback()
else:
await self.commit()
return FalseReturning True suppresses the exception. This is useful when you have handled the error inside __aexit__ and do not want it to propagate further. However, suppressing an exception without a clear reason can hide bugs, so use True sparingly.
If __aexit__ itself raises an exception, that exception takes precedence over the original one. This can obscure the root cause. To avoid hiding the original exception, catch cleanup errors inside __aexit__ and decide whether to re-raise the original exception after cleanup.
Practical Example: Async Resource Cleanup
Consider an async HTTP client that needs to close its session when done. Using __aexit__ ensures the session is closed even if the request fails:
import aiohttp
class AsyncHTTPSession:
def __init__(self):
self._session = None
async def __aenter__(self):
self._session = aiohttp.ClientSession()
return self._session
async def __aexit__(self, exc_type, exc, tb):
await self._session.close()
return FalseYou can then use it as:
async with AsyncHTTPSession() as session:
async with session.get('https://example.com') as resp:
print(resp.status)The __aexit__ method guarantees that close() is awaited, which releases the connection pool cleanly. Without it, you would need to manually close the session in a finally block, which is error-prone.
Common Mistakes and Pitfalls
One frequent mistake is forgetting to make __aexit__ awaitable. If you define it with a regular def and do not return an awaitable, Python raises a TypeError when the async with block exits, because it expects an awaitable.
Another pitfall is returning a truthy value unintentionally. For example, if __aexit__ returns the result of an await that evaluates to True, the exception will be suppressed. Always return an explicit boolean or None.
Also, remember that __aexit__ is called even if an exception occurs inside the block. If you need to distinguish between normal exit and exception exit, check exc_type. Do not assume that cleanup is only needed on success.
Finally, avoid performing blocking I/O inside __aexit__. Since it is a coroutine, it runs on the event loop. Blocking calls will stall the entire loop. Use await with non-blocking operations, or offload blocking work to a thread pool with asyncio.to_thread.
Performance and Concurrency Considerations
Async context managers exist to avoid blocking the event loop during resource acquisition and release. The __aexit__ method should be non-blocking and should not hold locks or perform CPU-bound work. If cleanup involves a long-running operation, consider using asyncio.shield to prevent cancellation from interrupting the cleanup, or handle cancellation explicitly.
When multiple async with blocks are nested, each __aexit__ runs in exit order, normally innermost first. This is similar to synchronous context managers. However, because each __aexit__ is a coroutine, they are scheduled on the event loop. If one __aexit__ awaits on a slow operation, it can delay the exit of outer blocks. Be mindful of the total time spent in cleanup, especially in high-concurrency scenarios.
Another concurrency concern is exception handling. If __aexit__ suppresses an exception, the async with block completes normally. This can affect the control flow of concurrent tasks. Make sure that suppressing exceptions is intentional and that the state of the system remains consistent.
When to Use aexit vs. try/finally
While you can always use try/finally with await for cleanup, async with and __aexit__ provide a cleaner, more reusable pattern. The context manager encapsulates the acquisition and release logic, so you do not repeat it at every call site. This is especially valuable for libraries that expose resources to users.
However, try/finally is still useful when you need to handle cleanup that is not tied to a specific object, or when you need to perform multiple cleanup steps in a specific order. For example:
resource = await acquire()
try:
await use(resource)
finally:
await release(resource)This pattern is equivalent to a simple context manager, but it does not enforce the protocol. Use __aexit__ when you want to provide a reusable, composable resource manager that integrates with async with.
In summary, __aexit__ is the exit point of the async context manager protocol. Implementing it correctly ensures that resources are released promptly, exceptions are handled predictably, and the event loop remains responsive. Pay attention to the return value, exception handling, and non-blocking behavior to write production-quality async code.
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.