exceptiongroup

1.3.1 verified Tue May 12 auth: no python install: verified quickstart: reviewed

A backport of PEP 654, providing exception groups and the 'except*' syntax for Python versions prior to 3.11. Current version: 1.3.1. Released on November 21, 2025. Maintained by The Trio Collective.

pip install exceptiongroup

Common errors

error ModuleNotFoundError: No module named 'exceptiongroup' ↓

cause The `exceptiongroup` library is a backport for Python versions prior to 3.11. If you are using Python 3.10 or older, you need to explicitly install the `exceptiongroup` package.

fix

pip install exceptiongroup

error NameError: name 'ExceptionGroup' is not defined ↓

cause The `ExceptionGroup` and `BaseExceptionGroup` classes were introduced in Python 3.11. If you are using an older Python version and have installed the `exceptiongroup` backport, you must import them from the `exceptiongroup` package, not assume they are built-in.

fix

from exceptiongroup import ExceptionGroup, BaseExceptionGroup

error SyntaxError: invalid syntax (when trying to use 'except*' on Python < 3.11) ↓

cause The `except*` syntax for handling exception groups is a new feature introduced in Python 3.11 (PEP 654). If you are using Python 3.10 or older, this syntax is not recognized by the interpreter, even if you have the `exceptiongroup` backport installed. The backport provides a `catch()` context manager for this functionality instead.

fix

For Python versions prior to 3.11, use the exceptiongroup.catch() context manager instead of except* syntax:

from exceptiongroup import catch

with catch({ValueError: lambda eg: print(f"Caught ValueErrors: {eg.exceptions}")}):
    raise ExceptionGroup("errors", [ValueError("bad value"), TypeError("bad type")])

error SyntaxError: cannot have both except and except* on the same try ↓

cause Python's exception handling syntax does not allow mixing traditional `except` clauses with the newer `except*` clauses within the same `try` block. This rule applies to Python 3.11+ where `except*` is native, and conceptually to the `exceptiongroup.catch()` backport which acts similarly.

fix

Separate your exception handling into different try blocks if you need to use both traditional except and except* (or the exceptiongroup.catch() equivalent), or refactor to use except* exclusively to handle individual exception types within an exception group.

try:
    # Code that might raise an ExceptionGroup
    pass
except* ValueError:
    print("Caught a ValueError subgroup")
try:
    # Code that might raise a non-group exception
    pass
except TypeError:
    print("Caught a TypeError")

Warnings

breaking The 'except*' syntax introduced in PEP 654 is not available in Python versions prior to 3.11. Ensure compatibility with your Python version. ↓

fix Use the 'exceptiongroup' package to backport exception groups and 'except*' syntax to earlier Python versions.

gotcha The 'catch' function from 'exceptiongroup' is necessary to handle exception groups in Python versions prior to 3.11. Omitting it will result in unhandled exceptions. ↓

fix Import and use 'catch' from 'exceptiongroup' to handle exception groups appropriately.

breaking The application failed to locate necessary files or directories, resulting in an '[Errno 2] No such file or directory' error. This indicates that critical files (e.g., 'unknown1.txt', 'unknown2.txt') expected by the application or its dependencies were not found. ↓

fix Ensure that all required files and their parent directories are present and accessible at the expected paths during runtime. This may involve checking build processes, deployment configurations, or runtime environment variables that specify file locations.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.04s 18.2M

3.10 slim (glibc) - - 0.02s 19M

3.11 alpine (musl) - - 0.06s 20.1M

3.11 slim (glibc) - - 0.04s 21M

3.12 alpine (musl) - - 0.05s 12.0M

3.12 slim (glibc) - - 0.05s 12M

3.13 alpine (musl) - - 0.05s 11.2M

3.13 slim (glibc) - - 0.05s 12M

3.9 alpine (musl) - - 0.03s 17.7M

3.9 slim (glibc) - - 0.03s 18M

Imports

BaseExceptionGroup
```
from exceptiongroup import BaseExceptionGroup
```
Correct import path for BaseExceptionGroup
ExceptionGroup
```
from exceptiongroup import ExceptionGroup
```
Correct import path for ExceptionGroup
catch
```
from exceptiongroup import catch
```
Correct import path for catch function

Quickstart reviewed last tested: 2026-04-23

An example demonstrating the use of exception groups to handle multiple exceptions raised concurrently in Python 3.11 and later.

import asyncio
from exceptiongroup import BaseExceptionGroup, catch

async def read_file(filename):
    with open(filename) as f:
        data = f.read()
    return data

async def main():
    try:
        async with asyncio.TaskGroup() as g:
            g.create_task(read_file('unknown1.txt'))
            g.create_task(read_file('unknown2.txt'))
        print('All done')
    except* FileNotFoundError as eg:
        for e in eg.exceptions:
            print(e)

asyncio.run(main())