exceptiongroup

library1.3.1pypypi✓ verified 26d ago

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.

testing

pip install exceptiongroup

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · EXCEPTIONGROUP

exceptiongroup

testingpythonv1.3.1

Install

1.7s avg

Import

41ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.3.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.044s · 18.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.038s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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())

Debug

Known issues

breakingThe '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.

affects: <3.11

gotchaThe '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.

affects: <3.11

breakingThe 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.

affects: *

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'exceptiongroup'

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

NameError: name 'ExceptionGroup' is not defined

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

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

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:
```python
from exceptiongroup import catch

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

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

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.
```python
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")
```

Upgrade

Version history

1.3.1latest on PyPI · released Nov 21, 2025

Audit

Dependencies

triorequiredRequired for asynchronous operations

Agent activity

15 hits · last 30 days

node

Resources

githubhttps://github.com/agronholm/exceptiongroup ↗

packagehttps://pypi.org/project/exceptiongroup/ ↗

changeloghttps://github.com/agronholm/exceptiongroup/blob/main/CHANGES.rst ↗