Python 3.10: Fixing 'collections.MutableMapping' AttributeError

Overview

The AttributeError: module 'collections' has no attribute 'MutableMapping' error occurs when using Python 3.10 or later with packages that haven't been updated to account for changes in the Python standard library. This error commonly affects pip, requests, and other dependencies.

Root Cause

In Python 3.10, the MutableMapping class (along with other abstract base classes) was moved from the collections module to collections.abc. This change breaks backward compatibility with older packages that still reference collections.MutableMapping directly.

The error typically appears as:

AttributeError: module 'collections' has no attribute 'MutableMapping'

This often occurs in the dependency chain of packages like pkg_resources, pyparsing, requests, or urllib3 that haven't been updated for Python 3.10+ compatibility.

Solutions

1. Update Core Packages (Recommended)

The most reliable fix is to update your Python packages to versions compatible with Python 3.10:

pip install --upgrade pip wheel setuptools requests urllib3

If your system pip is broken, use the get-pip.py installer:

# Download the installer
wget https://bootstrap.pypa.io/get-pip.py

# Run with Python 3.10
python3.10 get-pip.py

WARNING

On Ubuntu/Debian systems, avoid mixing apt-managed Python packages with pip-installed ones. If you installed packages via apt, consider removing them first:

sudo apt remove python3-pip python-pip

2. Recreate Virtual Environments

If you're working in a virtual environment, recreate it with Python 3.10:

# Remove old environment
rm -rf .venv

# Create new environment
python3 -m venv .venv

# Activate and install dependencies
source .venv/bin/activate
pip install -r requirements.txt

3. Manual Code Patching (Temporary Fix)

For packages that can't be updated immediately, you can apply a runtime patch:

import collections.abc
import collections

# Backport MutableMapping for compatibility
collections.MutableMapping = collections.abc.MutableMapping

# Now import the problematic package
import requests  # or other affected package

For a more robust solution that works across Python versions:

import sys
import collections

if sys.version_info.major == 3 and sys.version_info.minor >= 10:
    from collections.abc import MutableMapping
else:
    from collections import MutableMapping

# Use MutableMapping in your code

4. Downgrade Python (Last Resort)

If compatibility issues persist, consider using Python 3.8 or 3.9:

# On Ubuntu/Debian
sudo apt install python3.9 python3.9-venv

# Create virtual environment with specific Python version
python3.9 -m venv .venv

Common Scenarios

Broken pip Installation

If your system pip is broken due to this error:

1. Remove current pip installation:

   sudo apt remove python3-pip

2. Install pip using ensurepip:

   python3.10 -m ensurepip

3. Upgrade pip immediately:

   python3.10 -m pip install --upgrade pip

Specific Package Issues

Some packages known to cause this issue and their solutions:

• pyparsing: Update to version 2.4.7 or later
• requests: Update to version 2.27.1 or later
• tornado: Update to version 6.0 or later
• urllib3: Update to latest version

pip install pyparsing>=2.4.7 requests>=2.27.1 tornado>=6.0

Prevention

To avoid similar issues in the future:

1. Use virtual environments for project-specific dependencies
2. Keep packages updated regularly
3. Test compatibility before upgrading Python versions
4. Pin dependencies in requirements.txt to known compatible versions

TIP

When upgrading Python, check the Python documentation for backward-incompatible changes that might affect your dependencies.

Conclusion

The collections.MutableMapping error in Python 3.10+ is a compatibility issue that can be resolved by updating packages, applying runtime patches, or in rare cases, downgrading Python versions. The recommended approach is to keep your dependencies updated and use virtual environments to isolate project dependencies.