Skip to main content

How to Resolve "AttributeError: module 'collections' has no attribute 'MutableMapping'"

When you upgrade to Python 3.10 or newer, you might suddenly encounter the AttributeError: module 'collections' has no attribute 'MutableMapping'. This error occurs because, as part of an effort to better organize the standard library, many Abstract Base Classes (ABCs), including MutableMapping, were moved from the top-level collections module to the collections.abc submodule.

This error can appear either from your own code or, more commonly, from an outdated third-party package (like pip or setuptools) that has not been updated for Python 3.10+. This guide will show you how to fix the error in all common scenarios.

Understanding the Error: The Move to collections.abc in Python 3.10​

In Python 3.9 and older, the import statement for MutableMapping was: from collections import MutableMapping

Starting with Python 3.10, this was deprecated and moved. The new, correct import path is: from collections.abc import MutableMapping

The AttributeError is a direct result of code trying to use the old import path on a Python 3.10+ interpreter.

Solution 1: Upgrade Core Packaging Tools (Most Common Fix)​

The most frequent cause of this error is running pip or another packaging tool that is itself outdated. An old version of setuptools, for example, will use the old import path and fail when run with a modern Python interpreter.

Example of the error scenario: you try to install a package and see a long traceback originating from pip or setuptools.

pip install some-package

# Traceback (most recent call last):
#   File "/path/to/pip/.../pep517_backend.py", line 87, in _get_backend
#   ...
#   File "/path/to/setuptools/_distutils/dist.py", line 29, in <module>
#     from collections import MutableMapping
# AttributeError: module 'collections' has no attribute 'MutableMapping'

Solution: the fix is to upgrade your core packaging tools. The latest versions are compatible with Python 3.10+.

python3 -m pip install --upgrade pip setuptools wheel
note

Using python3 -m pip is the most robust way to call pip, as it guarantees you are using the pip associated with your python3 interpreter.

After upgrading these tools, try your original pip install command again.

Solution 2: Fix Your Own Code (If You Import MutableMapping Directly)​

If the error comes from your own project's code, you need to update your import statements.

Exmaple of code causing the error:

# This import will fail on Python 3.10+
from collections import MutableMapping

class MyDict(MutableMapping):
    # ... implementation ...
    pass

Solution (Python 3.10+)​

Simply change the import path to collections.abc.

# ✅ Correct for Python 3.10 and newer
from collections.abc import MutableMapping

class MyDict(MutableMapping):
    # ... implementation ...
    pass

Solution (Cross-Compatible for All Python Versions)​

If you are writing a library that needs to support both older and newer Python versions, use a try-except block for the import. This is the standard compatibility pattern.

try:
    # For Python 3.10+
    from collections.abc import MutableMapping
except ImportError:
    # Fallback for Python 3.9 and older
    from collections import MutableMapping

class MyDict(MutableMapping):
    # ... implementation ...
    pass

This code will now run correctly on any modern Python version.

Solution 3: Downgrade Python (Last Resort)​

If you are working with a legacy project that has dependencies that cannot be upgraded, your only option may be to downgrade your Python interpreter to a version before 3.10 (e.g., Python 3.9).

warning

This is not a recommended long-term solution. By using an older version of Python, you miss out on new features, performance improvements, and critical security updates. This should only be used as a temporary measure while you plan a proper migration.

The Workaround:

  1. Download a Python 3.9.x installer from the official Python website.
  2. Install it and configure your project to use the 3.9 interpreter.

Conclusion​

Your SituationRecommended Solution
Error occurs when running pip install or other packaging commands.Upgrade your core tools: python3 -m pip install --upgrade pip setuptools wheel.
Error is in your own code (and you only need to support Python 3.10+).Change the import to from collections.abc import MutableMapping.
Error is in your own library (and you need to support multiple Python versions).Use the try-except ImportError compatibility pattern.
You cannot upgrade critical dependencies.Temporarily downgrade Python to version 3.9.

The AttributeError: module 'collections' has no attribute 'MutableMapping' is a clear signal of a Python 3.10+ compatibility issue. For most users, simply upgrading the core packaging tools will resolve the problem quickly and effectively.

Table of Contents